Relevant BUGIDs:

Purpose of commit: new feature

Commit summary:
---------------

2006-06-01  Thorsten Kukuk  <kukuk@thkukuk.de>

        * modules/pam_group/Makefile.am: Include Make.xml.rules.
        * modules/pam_group/group.conf.5.xml: New.
        * modules/pam_group/group.conf.5: New, generated from xml file.
        * modules/pam_group/pam_group.8.xml: New.
        * modules/pam_group/pam_group.8: New, generated from xml file.
        * modules/pam_group/README.xml: New.
        * modules/pam_group/README: Regenerated from xml file.

9 files changed, 520 insertions, 17 deletions

diff --git a/ChangeLog b/ChangeLog
index a82a998f..a5d7834b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 2006-06-01  Thorsten Kukuk  <kukuk@thkukuk.de>
 
+	* modules/pam_group/Makefile.am: Include Make.xml.rules.
+	* modules/pam_group/group.conf.5.xml: New.
+	* modules/pam_group/group.conf.5: New, generated from xml file.
+	* modules/pam_group/pam_group.8.xml: New.
+	* modules/pam_group/pam_group.8: New, generated from xml file.
+	* modules/pam_group/README.xml: New.
+	* modules/pam_group/README: Regenerated from xml file.
+
 	* modules/pam_ftp/Makefile.am: Include Make.xml.rules.
 	* modules/pam_ftp/pam_ftp.8.xml: New.
 	* modules/pam_ftp/pam_ftp.8: New, generated from xml file.
diff --git a/NEWS b/NEWS
index 17c6aca3..1e5ff0a9 100644
--- a/NEWS
+++ b/NEWS
@@ -4,7 +4,7 @@ Linux-PAM NEWS -- history of user-visible changes.
 * pam_tally: Fix support for large UIDs
 * Fixed all problems found by Coverity
 * Add manual page for pam_mkhomedir, pam_umask, pam_filter,
-  pam_issue, pam_ftp
+  pam_issue, pam_ftp, pam_group
 
 Release 0.99.4.0
 
diff --git a/modules/pam_group/Makefile.am b/modules/pam_group/Makefile.am
index e6a5e4ae..544fa12f 100644
--- a/modules/pam_group/Makefile.am
+++ b/modules/pam_group/Makefile.am
@@ -4,7 +4,10 @@
 
 CLEANFILES = *~
 
-EXTRA_DIST = README group.conf tst-pam_group
+EXTRA_DIST = README group.conf $(MANS) $(XMLS) tst-pam_group
+
+man_MANS = group.conf.5 pam_group.8
+XMLS = README.xml group.conf.5.xml pam_group.8.xml
 
 securelibdir = $(SECUREDIR)
 secureconfdir = $(SCONFIGDIR)
@@ -22,3 +25,10 @@ securelib_LTLIBRARIES = pam_group.la
 secureconf_DATA = group.conf
 
 TESTS = tst-pam_group
+
+if ENABLE_REGENERATE_MAN
+noinst_DATA = README
+README: pam_group.8.xml group.conf.5.xml
+-include $(top_srcdir)/Make.xml.rules
+endif
+
diff --git a/modules/pam_group/README b/modules/pam_group/README
index d579b858..71359bf1 100644
--- a/modules/pam_group/README
+++ b/modules/pam_group/README
@@ -1,23 +1,45 @@
+pam_group — PAM module for group access
 
-This is a help file for the pam_group module. It explains the need for
-pam_group and also the syntax of the /etc/security/group.conf file.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-1. Introduction
-===============
+DESCRIPTION
 
-It is desirable to give extra privileges to a user running a specific
-PAM aware application at various times of the day and on specific days
-or over various terminal lines by adding this user to extra groups.
+The pam_group PAM module does not authenticate the user, but instead it grants
+group memberships (in the credential setting phase of the authentication
+module) to the user. Such memberships are based on the service they are
+applying for.
 
-The pam_group module is intended to offer a configurable module that
-satisfies this purpose, within the context of Linux-PAM.
+By default rules for group memberships are taken from config file /etc/security
+/group.conf.
 
-2. the /etc/security/group.conf file
-===================================
+This module's usefulness relies on the file-systems accessible to the user. The
+point being that once granted the membership of a group, the user may attempt
+to create a setgid binary with a restricted group ownership. Later, when the
+user is not given membership to this group, they can recover group membership
+with the precompiled binary. The reason that the file-systems that the user has
+access to are so significant, is the fact that when a system is mounted nosuid
+the user is unable to create or execute such a binary file. For this module to
+provide any level of security, all file-systems that the user has write access
+to should be mounted nosuid.
 
-Its syntax is described in the sample group.conf file.
+The pam_group module fuctions in parallel with the /etc/group file. If the user
+is granted any groups based on the behavior of this module, they are granted in
+addition to those entries /etc/group (or equivalent).
 
-unrecognised rules are ignored (but an error is logged to syslog(3))
+EXAMPLES
+
+These are some example lines which might be specified in /etc/security/
+group.conf.
+
+Running 'xsh' on tty* (any ttyXXX device), the user 'us' is given access to the
+floppy (through membership of the floppy group)
+
+xsh;tty*&!ttyp*;us;Al0000-2400;floppy
+
+Running 'xsh' on tty* (any ttyXXX device), the user 'sword' is given access to
+games (through membership of the floppy group) after work hours.
+
+xsh; tty* ;sword;!Wk0900-1800;games, sound
+
+xsh; tty* ;*;Al0900-1800;floppy
 
---------------------
-Bugs to the list <pam-list@redhat.com>
diff --git a/modules/pam_group/README.xml b/modules/pam_group/README.xml
new file mode 100644
index 00000000..387d6987
--- /dev/null
+++ b/modules/pam_group/README.xml
@@ -0,0 +1,34 @@
+<?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 pamgroup SYSTEM "pam_group.8.xml">
+-->
+<!--
+<!ENTITY groupconf SYSTEM "group.conf.5.xml">
+-->
+]>
+
+<article>
+
+  <articleinfo>
+
+    <title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_group.8.xml" xpointer='xpointer(//refnamediv[@id = "pam_group-name"]/*)'/>
+    </title>
+
+  </articleinfo>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_group.8.xml" xpointer='xpointer(//refsect1[@id = "pam_group-description"]/*)'/>
+  </section>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="group.conf.5.xml" xpointer='xpointer(//refsect1[@id = "group.conf-examples"]/*)'/>
+  </section>
+
+</article>
diff --git a/modules/pam_group/group.conf.5 b/modules/pam_group/group.conf.5
new file mode 100644
index 00000000..82f21e8e
--- /dev/null
+++ b/modules/pam_group/group.conf.5
@@ -0,0 +1,70 @@
+.\" ** 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 "GROUP.CONF" "5" "06/01/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+group.conf \- configuration file for the pam_group module
+.SH "DESCRIPTION"
+.PP
+The pam_group PAM module does not authenticate the user, but instead it grants group memberships (in the credential setting phase of the authentication module) to the user. Such memberships are based on the service they are applying for.
+.PP
+For this module to function correctly there must be a correctly formatted
+\fI/etc/security/groups.conf\fR
+file present. White spaces are ignored and lines maybe extended with '\\' (escaped newlines). Text following a '#' is ignored to the end of the line.
+.PP
+The syntax of the lines is as follows:
+.PP
+\fIservices\fR;\fIttys\fR;\fIusers\fR;\fItimes\fR;\fIgroups\fR
+.PP
+The first field, the
+\fIservices\fR
+field, is a logic list of PAM service names that the rule applies to.
+.PP
+The second field, the
+\fItty\fR
+field, is a logic list of terminal names that this rule applies to.
+.PP
+The third field, the
+\fIusers\fR
+field, is a logic list of users or a netgroup of users to whom this rule applies.
+.PP
+For these items the simple wildcard '*' may be used only once. With netgroups no wildcards or logic operators are allowed.
+.PP
+The
+\fItimes\fR
+field is used to indicate "when" these groups are to be given to the user. The format here is a logic list of day/time\-range entries the days are specified by a sequence of two character entries, MoTuSa for example is Monday Tuesday and Saturday. Note that repeated days are unset MoMo = no day, and MoWk = all weekdays bar Monday. The two character combinations accepted are Mo Tu We Th Fr Sa Su Wk Wd Al, the last two being week\-end days and all 7 days of the week respectively. As a final example, AlFr means all days except Friday.
+.PP
+Each day/time\-range can be prefixed with a '!' to indicate "anything but". The time\-range part is two 24\-hour times HHMM separated by a hyphen indicating the start and finish time (if the finish time is smaller than the start time it is deemed to apply on the following day).
+.PP
+The
+\fIgroups\fR
+field is a comma or space separated list of groups that the user inherits membership of. These groups are added if the previous fields are satisfied by the user's request.
+.PP
+For a rule to be active, ALL of service+ttys+users must be satisfied by the applying process.
+.SH "EXAMPLES"
+.PP
+These are some example lines which might be specified in
+\fI/etc/security/group.conf\fR.
+.PP
+Running 'xsh' on tty* (any ttyXXX device), the user 'us' is given access to the floppy (through membership of the floppy group)
+.PP
+xsh;tty*&!ttyp*;us;Al0000\-2400;floppy
+.PP
+Running 'xsh' on tty* (any ttyXXX device), the user 'sword' is given access to games (through membership of the floppy group) after work hours.
+.PP
+xsh; tty* ;sword;!Wk0900\-1800;games, sound
+.PP
+xsh; tty* ;*;Al0900\-1800;floppy
+.SH "SEE ALSO"
+.PP
+\fBpam_group\fR(8),
+\fBpam.d\fR(5),
+\fBpam\fR(8)
+.SH "AUTHORS"
+.PP
+pam_group was written by Andrew G. Morgan <morgan@kernel.org>.
diff --git a/modules/pam_group/group.conf.5.xml b/modules/pam_group/group.conf.5.xml
new file mode 100644
index 00000000..036efb15
--- /dev/null
+++ b/modules/pam_group/group.conf.5.xml
@@ -0,0 +1,130 @@
+<?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="group.conf">
+
+  <refmeta>
+    <refentrytitle>group.conf</refentrytitle>
+    <manvolnum>5</manvolnum>
+    <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>group.conf</refname>
+    <refpurpose>configuration file for the pam_group module</refpurpose>
+  </refnamediv>
+
+  <refsect1 id='group.conf-description'>
+    <title>DESCRIPTION</title>
+
+    <para>
+      The pam_group PAM module does not authenticate the user, but instead
+      it grants group memberships (in the credential setting phase of the
+      authentication module) to the user. Such memberships are based on the
+      service they are applying for.
+    </para>
+    <para>
+      For this module to function correctly there must be a correctly
+      formatted <filename>/etc/security/groups.conf</filename> file present.
+      White spaces are ignored and lines maybe extended with '\' (escaped
+      newlines). Text following a '#' is ignored to the end of the line.
+   </para>
+
+    <para>
+      The syntax of the lines is as follows:
+    </para>
+
+    <para>
+      <replaceable>services</replaceable>;<replaceable>ttys</replaceable>;<replaceable>users</replaceable>;<replaceable>times</replaceable>;<replaceable>groups</replaceable>
+    </para>
+
+
+    <para>
+      The first field, the <replaceable>services</replaceable> field, is a logic list
+      of PAM service names that the rule applies to.
+    </para>
+
+    <para>
+      The second field, the <replaceable>tty</replaceable>
+      field, is a logic list of terminal names that this rule applies to.
+    </para>
+
+    <para>
+      The third field, the <replaceable>users</replaceable>
+      field, is a logic list of users or a netgroup of users to whom this
+      rule applies.
+    </para>
+
+    <para>
+      For these items the simple wildcard '*' may be used only once.
+      With netgroups no wildcards or logic operators are allowed.
+    </para>
+
+    <para>
+      The <replaceable>times</replaceable> field is used to indicate "when"
+      these groups are to be given to the user. The format here is a logic
+      list of day/time-range entries the days are specified by a sequence of
+      two character entries, MoTuSa for example is Monday Tuesday and Saturday.
+      Note that repeated days are unset MoMo = no day, and MoWk = all weekdays
+      bar Monday. The two character combinations accepted are Mo Tu We Th Fr Sa
+      Su Wk Wd Al, the last two being week-end days and all 7 days of the week
+      respectively. As a final example, AlFr means all days except Friday.
+    </para>
+    <para>
+      Each day/time-range can be prefixed with a '!' to indicate "anything but".
+      The time-range part is two 24-hour times HHMM separated by a hyphen
+      indicating the start and finish time (if the finish time is smaller
+      than the start time it is deemed to apply on the following day).
+    </para>
+
+    <para>
+      The <replaceable>groups</replaceable> field is a comma or space
+      separated list of groups that the user inherits membership of. These
+      groups are added if the previous fields are satisfied by the user's request.
+    </para>
+
+    <para>
+      For a rule to be active, ALL of service+ttys+users must be satisfied
+      by the applying process.
+    </para>
+  </refsect1>
+
+  <refsect1 id="group.conf-examples">
+    <title>EXAMPLES</title>
+    <para>
+      These are some example lines which might be specified in
+      <filename>/etc/security/group.conf</filename>.
+    </para>
+
+    <para>
+      Running 'xsh' on tty* (any ttyXXX device), the user 'us' is given access
+      to the floppy (through membership of the floppy group)
+    </para>
+    <para>xsh;tty*&amp;!ttyp*;us;Al0000-2400;floppy</para>
+
+    <para>
+      Running 'xsh' on tty* (any ttyXXX device), the user 'sword' is given access
+      to games (through membership of the floppy group) after work hours.
+    </para>
+    <para>xsh; tty* ;sword;!Wk0900-1800;games, sound</para>
+    <para>xsh; tty* ;*;Al0900-1800;floppy</para>
+
+  </refsect1>
+
+  <refsect1 id="group.conf-see_also">
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry><refentrytitle>pam_group</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+  <refsect1 id="group.conf-author">
+    <title>AUTHORS</title>
+    <para>
+      pam_group was written by Andrew G. Morgan &lt;morgan@kernel.org&gt;.
+    </para>
+  </refsect1>
+</refentry>
diff --git a/modules/pam_group/pam_group.8 b/modules/pam_group/pam_group.8
new file mode 100644
index 00000000..b754dc4c
--- /dev/null
+++ b/modules/pam_group/pam_group.8
@@ -0,0 +1,72 @@
+.\" ** 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_GROUP" "8" "06/01/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_group \- PAM module for group access
+.SH "SYNOPSIS"
+.HP 13
+\fBpam_group.so\fR
+.SH "DESCRIPTION"
+.PP
+The pam_group PAM module does not authenticate the user, but instead it grants group memberships (in the credential setting phase of the authentication module) to the user. Such memberships are based on the service they are applying for.
+.PP
+By default rules for group memberships are taken from config file
+\fI/etc/security/group.conf\fR.
+.PP
+This module's usefulness relies on the file\-systems accessible to the user. The point being that once granted the membership of a group, the user may attempt to create a
+\fBsetgid\fR
+binary with a restricted group ownership. Later, when the user is not given membership to this group, they can recover group membership with the precompiled binary. The reason that the file\-systems that the user has access to are so significant, is the fact that when a system is mounted
+\fInosuid\fR
+the user is unable to create or execute such a binary file. For this module to provide any level of security, all file\-systems that the user has write access to should be mounted
+\fInosuid\fR.
+.PP
+The pam_group module fuctions in parallel with the
+\fI/etc/group\fR
+file. If the user is granted any groups based on the behavior of this module, they are granted
+\fIin addition\fR
+to those entries
+\fI/etc/group\fR
+(or equivalent).
+.SH "MODULE SERVICES PROVIDED"
+.PP
+Only the
+\fBauth\fR
+service is supported.
+.SH "RETURN VALUES"
+.TP
+PAM_SUCCESS
+group membership was granted.
+.TP
+PAM_ABORT
+Not all relevant data could be gotten.
+.TP
+PAM_BUF_ERR
+Memory buffer error.
+.TP
+PAM_CRED_ERR
+Group membership was not granted.
+.TP
+PAM_IGNORE
+\fBpam_sm_authenticate\fR
+was called which does nothing.
+.TP
+PAM_USER_UNKNOWN
+The user is not known to the system.
+.SH "FILES"
+.TP
+\fI/etc/security/group.conf\fR
+Default configuration file
+.SH "SEE ALSO"
+.PP
+\fBgroup.conf\fR(5),
+\fBpam.d\fR(8),
+\fBpam\fR(8).
+.SH "AUTHORS"
+.PP
+pam_group was written by Andrew G. Morgan <morgan@kernel.org>.
diff --git a/modules/pam_group/pam_group.8.xml b/modules/pam_group/pam_group.8.xml
new file mode 100644
index 00000000..6e6c0498
--- /dev/null
+++ b/modules/pam_group/pam_group.8.xml
@@ -0,0 +1,157 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<refentry id='pam_group'>
+
+  <refmeta>
+    <refentrytitle>pam_group</refentrytitle>
+    <manvolnum>8</manvolnum>
+    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id='pam_group-name'>
+    <refname>pam_group</refname>
+    <refpurpose>
+      PAM module for group access
+    </refpurpose>
+  </refnamediv>
+
+<!-- body begins here -->
+
+  <refsynopsisdiv>
+    <cmdsynopsis id="pam_group-cmdsynopsis">
+      <command>pam_group.so</command>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1 id="pam_group-description">
+    <title>DESCRIPTION</title>
+    <para>
+      The pam_group PAM module does not authenticate the user, but instead
+      it grants group memberships (in the credential setting phase of the
+      authentication module) to the user. Such memberships are based on the
+      service they are applying for.
+    </para>
+    <para>
+      By default rules for group memberships are taken from config file
+      <filename>/etc/security/group.conf</filename>.
+    </para>
+    <para>
+      This module's usefulness relies on the file-systems
+      accessible to the user. The point being that once granted the
+      membership of a group, the user may attempt to create a
+      <function>setgid</function> binary with a restricted group ownership.
+      Later, when the user is not given membership to this group, they can
+      recover group membership with the precompiled binary. The reason that
+      the file-systems that the user has access to are so significant, is the
+      fact that when a system is mounted <emphasis>nosuid</emphasis> the user
+      is unable to create or execute such a binary file. For this module to
+      provide any level of security, all file-systems that the user has write
+      access to should be mounted <emphasis>nosuid</emphasis>.
+    </para>
+    <para>
+      The pam_group module fuctions in parallel with the
+      <filename>/etc/group</filename> file. If the user is granted any groups
+      based on the behavior of this module, they are granted
+      <emphasis>in addition</emphasis> to those entries
+      <filename>/etc/group</filename> (or equivalent).
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_group-services">
+    <title>MODULE SERVICES PROVIDED</title>
+    <para>
+      Only the <option>auth</option> service is supported.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_group-return_values">
+    <title>RETURN VALUES</title>
+    <variablelist>
+      <varlistentry>
+        <term>PAM_SUCCESS</term>
+        <listitem>
+           <para>
+             group membership was granted.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_ABORT</term>
+        <listitem>
+           <para>
+             Not all relevant data could be gotten.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_BUF_ERR</term>
+        <listitem>
+          <para>
+            Memory buffer error.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_CRED_ERR</term>
+        <listitem>
+          <para>
+            Group membership was not granted.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_IGNORE</term>
+        <listitem>
+           <para>
+             <function>pam_sm_authenticate</function> was called which does nothing.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_USER_UNKNOWN</term>
+        <listitem>
+           <para>
+             The user is not known to the system.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="pam_group-files">
+    <title>FILES</title>
+    <variablelist>
+      <varlistentry>
+        <term><filename>/etc/security/group.conf</filename></term>
+        <listitem>
+          <para>Default configuration file</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="pam_group-see_also">
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>group.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_group-authors">
+    <title>AUTHORS</title>
+    <para>
+      pam_group was written by Andrew G. Morgan &lt;morgan@kernel.org&gt;.
+    </para>
+  </refsect1>
+</refentry>