summaryrefslogtreecommitdiff
path: root/modules/pam_filter
diff options
context:
space:
mode:
authorThorsten Kukuk <kukuk@thkukuk.de>2006-06-01 11:41:18 +0000
committerThorsten Kukuk <kukuk@thkukuk.de>2006-06-01 11:41:18 +0000
commit4eb2a80c4074e8495e2dbdac2af9532c0d355ced (patch)
tree12fb86c6a62824139bad02f01658890df1c686cd /modules/pam_filter
parent6a9e09d57a7722a3a73d3405ef63d3c46f1f7673 (diff)
Relevant BUGIDs:
Purpose of commit: new feature Commit summary: --------------- 2006-06-01 Thorsten Kukuk <kukuk@thkukuk.de> * modules/pam_issue/Makefile.am: Include Make.xml.rules. * modules/pam_issue/pam_issue.8.xml: New. * modules/pam_issue/pam_issue.8: New, generated from xml file. * modules/pam_issue/README.xml: New. * modules/pam_issue/README: Regenerated from xml file. * modules/pam_filter/Makefile.am: Include Make.xml.rules. * modules/pam_filter/pam_filter.8.xml: New. * modules/pam_filter/pam_filter.8: New, generated from xml file. * modules/pam_filter/README.xml: New. * modules/pam_filter/README: Regenerated from xml file.
Diffstat (limited to 'modules/pam_filter')
-rw-r--r--modules/pam_filter/Makefile.am12
-rw-r--r--modules/pam_filter/README120
-rw-r--r--modules/pam_filter/README.xml41
-rw-r--r--modules/pam_filter/pam_filter.8134
-rw-r--r--modules/pam_filter/pam_filter.8.xml263
5 files changed, 501 insertions, 69 deletions
diff --git a/modules/pam_filter/Makefile.am b/modules/pam_filter/Makefile.am
index ca8d5491..b218bffb 100644
--- a/modules/pam_filter/Makefile.am
+++ b/modules/pam_filter/Makefile.am
@@ -6,7 +6,10 @@ SUBDIRS = upperLOWER
CLEANFILES = *~
-EXTRA_DIST = README tst-pam_filter
+EXTRA_DIST = README $(MANS) $(XMLS) tst-pam_filter
+
+man_MANS = pam_filter.8
+XMLS = README.xml pam_filter.8.xml
securelibdir = $(SECUREDIR)
secureconfdir = $(SCONFIGDIR)
@@ -22,3 +25,10 @@ include_HEADERS=pam_filter.h
securelib_LTLIBRARIES = pam_filter.la
TESTS = tst-pam_filter
+
+if ENABLE_REGENERATE_MAN
+noinst_DATA = README
+README: pam_filter.8.xml
+-include $(top_srcdir)/Make.xml.rules
+endif
+
diff --git a/modules/pam_filter/README b/modules/pam_filter/README
index 850f1145..4d4e2194 100644
--- a/modules/pam_filter/README
+++ b/modules/pam_filter/README
@@ -1,94 +1,78 @@
-#
-# $Id$
-#
-# This describes the behavior of this module with respect to the
-# /etc/pam.conf file.
-#
-# writen by Andrew Morgan <morgan@parc.power.net>
-#
+pam_filter — PAM filter module
-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.
+DESCRIPTION
-recognized flags are:
+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.
- debug print some information to syslog(3)
+To function this module requires filters to be installed on the system. 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).
- 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)
+Each component of the module has the potential to invoke the desired filter.
+The filter is always execv(2) with the privilege of the calling application and
+not that of the user. For this reason it cannot usually be killed by the user
+without closing their session.
- non_term don't try to set the PAM_TTY item
+OPTIONS
- 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.
+debug
- The distinction between run1 and run2
- is which of the two functions of
- the given management-type triggers the
- execution of the indicated filter.
+ Print debug information.
- type: run1 run2
- ----- ---- ----
+new_term
- auth pam_sm_authenticate pam_sm_setcred
+ The default action of the filter is to set the 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 PAM_TTY to the filtered
+ pseudo-terminal.
- account [ pam_sm_acct_mgmt (either is good) ]
+non_term
- session pam_sm_open_session pam_sm_close_session
+ don't try to set the PAM_TTY item.
- password pam_sm_chauthtok/PRELIM pam_sm_chauthtok/UPDATE
+runX
-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.
+ 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.
-What a filter program should expect:
-------------------------------------
+ Permitted values for X are 1 and 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 pam(3) manual page. Basically, for each management group
+ there are up to two ways of calling the module's functions. In the case of
+ the authentication and session components there are actually two separate
+ functions. For the case of authentication, these functions are
+ pam_authenticate(3) and pam_setcred(3), here run1 means run the filter from
+ the pam_authenticate function and run2 means run the filter from
+ pam_setcred. In the case of the session modules, run1 implies that the
+ filter is invoked at the pam_open_session(3) stage, and run2 for
+ pam_close_session(3).
-Definitions for filter programs (which may be locally designed) are
-contained in the <security/pam_filter.h> file.
+ For the case of the account component. Either run1 or run2 may be used.
-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.
+ For the case of the password component, run1 is used to indicate that the
+ filter is run on the first occasion of pam_chauthtok(3) (the
+ PAM_PRELIM_CHECK phase) and run2 is used to indicate that the filter is run
+ on the second occasion (the PAM_UPDATE_AUTHTOK phase).
-Here is a list of the environment variables that a filter should
-expect:
+filter
- 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)
+ The full pathname of the filter to be run and any command line arguments
+ that the filter might expect.
-[This list is likely to grow. If you want something added, email me!]
+EXAMPLES
-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.
+Add the following line to /etc/pam.d/login to see how to configure login to
+transpose upper and lower case letters once the user has logged in:
-Existing filters:
------------------
+ session required pam_filter.so run1 /lib/security/pam_filter/upperLOWER
-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.
+AUTHOR
-Andrew G. Morgan <morgan@parc.power.net> 1996/5/27
+pam_filter was written by Andrew G. Morgan <morgan@kernel.org>.
diff --git a/modules/pam_filter/README.xml b/modules/pam_filter/README.xml
new file mode 100644
index 00000000..b76cb743
--- /dev/null
+++ b/modules/pam_filter/README.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.docbook.org/xml/4.3/docbookx.dtd"
+[
+<!--
+<!ENTITY pamaccess SYSTEM "pam_filter.8.xml">
+-->
+]>
+
+<article>
+
+ <articleinfo>
+
+ <title>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="pam_filter.8.xml" xpointer='xpointer(//refnamediv[@id = "pam_filter-name"]/*)'/>
+ </title>
+
+ </articleinfo>
+
+ <section>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="pam_filter.8.xml" xpointer='xpointer(//refsect1[@id = "pam_filter-description"]/*)'/>
+ </section>
+
+ <section>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="pam_filter.8.xml" xpointer='xpointer(//refsect1[@id = "pam_filter-options"]/*)'/>
+ </section>
+
+ <section>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="pam_filter.8.xml" xpointer='xpointer(//refsect1[@id = "pam_filter-examples"]/*)'/>
+ </section>
+
+ <section>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="pam_filter.8.xml" xpointer='xpointer(//refsect1[@id = "pam_filter-author"]/*)'/>
+ </section>
+
+</article>
diff --git a/modules/pam_filter/pam_filter.8 b/modules/pam_filter/pam_filter.8
new file mode 100644
index 00000000..c0f0113f
--- /dev/null
+++ b/modules/pam_filter/pam_filter.8
@@ -0,0 +1,134 @@
+.\" ** You probably do not want to edit this file directly **
+.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
+.\" Instead of manually editing it, you probably should edit the DocBook XML
+.\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
+.TH "PAM_FILTER" "8" "05/30/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_filter \- PAM filter module
+.SH "SYNOPSIS"
+.HP 14
+\fBpam_filter.so\fR [debug] [new_term] [non_term] run1|run2 \fIfilter\fR [\fI...\fR]
+.SH "DESCRIPTION"
+.PP
+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.
+.PP
+To function this module requires
+\fIfilters\fR
+to be installed on the system. 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).
+.PP
+Each component of the module has the potential to invoke the desired filter. The filter is always
+\fBexecv\fR(2)
+with the privilege of the calling application and
+\fInot\fR
+that of the user. For this reason it cannot usually be killed by the user without closing their session.
+.SH "OPTIONS"
+.PP
+.TP
+\fBdebug\fR
+Print debug information.
+.TP
+\fBnew_term\fR
+The default action of the filter is to set the
+\fIPAM_TTY\fR
+item to indicate the terminal that the user is using to connect to the application. This argument indicates that the filter should set
+\fIPAM_TTY\fR
+to the filtered pseudo\-terminal.
+.TP
+\fBnon_term\fR
+don't try to set the
+\fIPAM_TTY\fR
+item.
+.TP
+\fBrunX\fR
+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.
+.sp
+Permitted values for
+\fIX\fR
+are
+\fI1\fR
+and
+\fI2\fR. These indicate the precise time that the filter is to be run. To understand this concept it will be useful to have read the
+\fBpam\fR(3)
+manual page. Basically, for each management group there are up to two ways of calling the module's functions. In the case of the
+\fIauthentication\fR
+and
+\fIsession\fR
+components there are actually two separate functions. For the case of authentication, these functions are
+\fBpam_authenticate\fR(3)
+and
+\fBpam_setcred\fR(3), here
+\fBrun1\fR
+means run the filter from the
+\fBpam_authenticate\fR
+function and
+\fBrun2\fR
+means run the filter from
+\fBpam_setcred\fR. In the case of the session modules,
+\fIrun1\fR
+implies that the filter is invoked at the
+\fBpam_open_session\fR(3)
+stage, and
+\fIrun2\fR
+for
+\fBpam_close_session\fR(3).
+.sp
+For the case of the account component. Either
+\fIrun1\fR
+or
+\fIrun2\fR
+may be used.
+.sp
+For the case of the password component,
+\fIrun1\fR
+is used to indicate that the filter is run on the first occasion of
+\fBpam_chauthtok\fR(3)
+(the
+\fIPAM_PRELIM_CHECK\fR
+phase) and
+\fIrun2\fR
+is used to indicate that the filter is run on the second occasion (the
+\fIPAM_UPDATE_AUTHTOK\fR
+phase).
+.TP
+\fBfilter\fR
+The full pathname of the filter to be run and any command line arguments that the filter might expect.
+.SH "MODULE SERVICES PROVIDED"
+.PP
+The services
+\fBauth\fR,
+\fBaccount\fR,
+\fBpassword\fR
+and
+\fBsession\fR
+are supported.
+.SH "RETURN VALUES"
+.PP
+.TP
+PAM_SUCCESS
+The new filter was set successfull.
+.TP
+PAM_ABORT
+Critical error, immediate abort.
+.SH "EXAMPLES"
+.PP
+Add the following line to
+\fI/etc/pam.d/login\fR
+to see how to configure login to transpose upper and lower case letters once the user has logged in:
+.sp
+.nf
+ session required pam_filter.so run1 /lib/security/pam_filter/upperLOWER
+
+.fi
+.sp
+.SH "SEE ALSO"
+.PP
+\fBpam.conf\fR(5),
+\fBpam.d\fR(8),
+\fBpam\fR(8)
+.SH "AUTHOR"
+.PP
+pam_filter was written by Andrew G. Morgan <morgan@kernel.org>.
diff --git a/modules/pam_filter/pam_filter.8.xml b/modules/pam_filter/pam_filter.8.xml
new file mode 100644
index 00000000..f4d86b66
--- /dev/null
+++ b/modules/pam_filter/pam_filter.8.xml
@@ -0,0 +1,263 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<refentry id="pam_filter">
+
+ <refmeta>
+ <refentrytitle>pam_filter</refentrytitle>
+ <manvolnum>8</manvolnum>
+ <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="pam_filter-name">
+ <refname>pam_filter</refname>
+ <refpurpose>PAM filter module</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis id="pam_filter-cmdsynopsis">
+ <command>pam_filter.so</command>
+ <arg choice="opt">
+ debug
+ </arg>
+ <arg choice="opt">
+ new_term
+ </arg>
+ <arg choice="opt">
+ non_term
+ </arg>
+ <arg choice="plain">
+ run1|run2
+ </arg>
+ <arg choice="plain">
+ <replaceable>filter</replaceable>
+ </arg>
+ <arg choice="opt">
+ <replaceable>...</replaceable>
+ </arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id="pam_filter-description">
+
+ <title>DESCRIPTION</title>
+
+ <para>
+ 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.
+ </para>
+ <para>
+ To function this module requires <emphasis>filters</emphasis> to be
+ installed on the system.
+ 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).
+ </para>
+ <para>
+ Each component of the module has the potential to invoke the
+ desired filter. The filter is always
+ <citerefentry>
+ <refentrytitle>execv</refentrytitle><manvolnum>2</manvolnum>
+ </citerefentry> with the privilege of the calling application
+ and <emphasis>not</emphasis> that of the user. For this reason it
+ cannot usually be killed by the user without closing their session.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pam_filter-options">
+
+ <title>OPTIONS</title>
+ <para>
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ <option>debug</option>
+ </term>
+ <listitem>
+ <para>
+ Print debug information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>new_term</option>
+ </term>
+ <listitem>
+ <para>
+ The default action of the filter is to set the
+ <emphasis>PAM_TTY</emphasis> item to indicate the
+ terminal that the user is using to connect to the
+ application. This argument indicates that the filter
+ should set <emphasis>PAM_TTY</emphasis> to the filtered
+ pseudo-terminal.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>non_term</option>
+ </term>
+ <listitem>
+ <para>
+ don't try to set the <emphasis>PAM_TTY</emphasis> item.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>runX</option>
+ </term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ <para>
+ Permitted values for <emphasis>X</emphasis> are
+ <emphasis>1</emphasis> and <emphasis>2</emphasis>. These
+ indicate the precise time that the filter is to be run.
+ To understand this concept it will be useful to have read
+ the <citerefentry>
+ <refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry> manual page.
+ Basically, for each management group there are up to two ways
+ of calling the module's functions.
+ In the case of the <emphasis>authentication</emphasis> and
+ <emphasis>session</emphasis> components there are actually
+ two separate functions. For the case of authentication, these
+ functions are
+ <citerefentry>
+ <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry> and
+ <citerefentry>
+ <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>, here <option>run1</option> means run the
+ filter from the <function>pam_authenticate</function> function
+ and <option>run2</option> means run the filter from
+ <function>pam_setcred</function>. In the case of the
+ session modules, <emphasis>run1</emphasis> implies
+ that the filter is invoked at the
+ <citerefentry>
+ <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry> stage, and <emphasis>run2</emphasis> for
+ <citerefentry>
+ <refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ </para>
+ <para>
+ For the case of the account component. Either
+ <emphasis>run1</emphasis> or <emphasis>run2</emphasis>
+ may be used.
+ </para>
+ <para>
+ For the case of the password component, <emphasis>run1</emphasis>
+ is used to indicate that the filter is run on the first
+ occasion of
+ <citerefentry>
+ <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry> (the <emphasis>PAM_PRELIM_CHECK</emphasis>
+ phase) and <emphasis>run2</emphasis> is used to indicate
+ that the filter is run on the second occasion (the
+ <emphasis>PAM_UPDATE_AUTHTOK</emphasis> phase).
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>filter</option>
+ </term>
+ <listitem>
+ <para>
+ The full pathname of the filter to be run and any command line
+ arguments that the filter might expect.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+ </refsect1>
+
+ <refsect1 id="pam_filter-services">
+ <title>MODULE SERVICES PROVIDED</title>
+ <para>
+ The services <option>auth</option>, <option>account</option>,
+ <option>password</option> and <option>session</option> are supported.
+ </para>
+ </refsect1>
+
+ <refsect1 id='pam_filter-return_values'>
+ <title>RETURN VALUES</title>
+ <para>
+ <variablelist>
+
+ <varlistentry>
+ <term>PAM_SUCCESS</term>
+ <listitem>
+ <para>
+ The new filter was set successfull.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PAM_ABORT</term>
+ <listitem>
+ <para>
+ Critical error, immediate abort.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 id='pam_filter-examples'>
+ <title>EXAMPLES</title>
+ <para>
+ Add the following line to <filename>/etc/pam.d/login</filename> to
+ see how to configure login to transpose upper and lower case letters
+ once the user has logged in:
+
+ <programlisting>
+ session required pam_filter.so run1 /lib/security/pam_filter/upperLOWER
+ </programlisting>
+ </para>
+ </refsect1>
+
+ <refsect1 id='pam_filter-see_also'>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam.d</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+
+ <refsect1 id='pam_filter-author'>
+ <title>AUTHOR</title>
+ <para>
+ pam_filter was written by Andrew G. Morgan &lt;morgan@kernel.org&gt;.
+ </para>
+ </refsect1>
+
+</refentry>
+<!-- vim: sw=2
+-->