granicus.if.org Git - linux-pam/blob - modules/pam_filter/README

   1 #
   2 # $Id$
   3 #
   4 # This describes the behavior of this module with respect to the
   5 # /etc/pam.conf file.
   6 #
   7 # writen by Andrew Morgan <morgan@parc.power.net>
   8 #
   9
  10 This module is intended to be a platform for providing access to all
  11 of the input/output that passes between the user and the application.
  12 It is only suitable for tty-based and (stdin/stdout) applications. And
  13 is only known to work on Linux based systems.
  14
  15 The action of the module is dictated by the arguments it is given in
  16 the pam.conf file.
  17
  18 recognized flags are:
  19
  20         debug                   print some information to syslog(3)
  21
  22         new_term                set the PAM_TTY item to the new filtered
  23                                 terminal (the default is to set it
  24                                 to be that of the users terminal)
  25
  26         non_term                don't try to set the PAM_TTY item
  27
  28         run1/run2               these arguments indicate that the
  29                                 module should separate the application
  30                                 from the user and insert a filter
  31                                 program between them. The pathname of
  32                                 the filter program follows the 'runN'
  33                                 argument. Arguments that follow this
  34                                 pathname are passed as arguments to
  35                                 the filter program.
  36
  37                                 The distinction between run1 and run2
  38                                 is which of the two functions of
  39                                 the given management-type triggers the
  40                                 execution of the indicated filter.
  41
  42         type:           run1                    run2
  43         -----           ----                    ----
  44
  45         auth            pam_sm_authenticate     pam_sm_setcred
  46
  47         account         [  pam_sm_acct_mgmt  (either is good)  ]
  48
  49         session         pam_sm_open_session     pam_sm_close_session
  50
  51         password        pam_sm_chauthtok/PRELIM pam_sm_chauthtok/UPDATE
  52
  53 Note, in the case of 'password' PRELIM/UPDATE indicates which of the
  54 two calls to pam_sm_chauthtok from libpam (not the application) will
  55 trigger the filter.
  56
  57 What a filter program should expect:
  58 ------------------------------------
  59
  60 Definitions for filter programs (which may be locally designed) are
  61 contained in the <security/pam_filter.h> file.
  62
  63 Arguments are not passed to the filter on the command line, since this
  64 is plainly visible when a user types 'ps -a'. Instead they are passed
  65 as the filter's environment. Other information is passed in this way
  66 too.
  67
  68 Here is a list of the environment variables that a filter should
  69 expect:
  70
  71         ARGS="filter_path_name argument list"
  72         SERVICE="service_name"  (as it appears in /etc/pam.conf)
  73         USER="username"
  74         TYPE="module_fn"  (the name of the function in pam_filter.so
  75                            that invoked the filter)
  76
  77 [This list is likely to grow. If you want something added, email me!]
  78
  79 Among other things this module is intended to provide a useful means
  80 of logging the activity of users in as discrete a manner as possible.
  81
  82 Existing filters:
  83 -----------------
  84
  85 Currently, there is a single supplied filter (upperLOWER).  The effect
  86 of using this filter is to transpose upper and lower case letters
  87 between the user and the application. This is really annoying when you
  88 try the 'xsh' example application! ;)
  89
  90 TODO: provide more filters...
  91       Decide if providing stderr interception is really overkill.
  92
  93 Andrew G. Morgan <morgan@parc.power.net> 1996/5/27
  94