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

<sect1>The group access module

<sect2>Synopsis

<p>
<descrip>

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

<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>
authentication

<tag><bf>Cryptographically sensitive:</bf></tag>
	
<tag><bf>Security rating:</bf></tag>
Sensitive to <em/setgid/ status of file-systems accessible to users.

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

<tag><bf>System dependencies:</bf></tag>
Requires an <tt>/etc/security/group.conf</tt> file. Can be compiled
with or without <tt/libpwdb/.

<tag><bf>Network aware:</bf></tag>
Only through correctly set <tt/PAM_TTY/ item.

</descrip>

<sect2>Overview of module

<p>
This module provides group-settings based on the user's name and the
terminal they are requesting a given service from. It takes note of
the time of day.

<sect2>Authentication component

<p>
<descrip>

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

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

This 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 group memberships are listed in
text form in the <tt>/etc/security/group.conf</tt> file.

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

For this module to function correctly there must be a correctly
formatted <tt>/etc/security/groups.conf</tt> file present. The format
of this file is as follows. Group memberships are given based on the
service application satisfying any combination of lines in the
configuration file. Each line (barring comments which are preceded by
`<tt/#/' marks) has the following
syntax:
<tscreen>
<verb>
services   ;   ttys   ;   users   ;   times   ;   groups
</verb>
</tscreen>
Here the first four fields share the syntax of the <tt>pam_time</tt>
configuration file; <tt>/etc/security/pam_time.conf</tt>, and the last
field, the <tt/groups/ field, is a comma (or space) separated list of
the text-names of a selection of groups. If the users application for
service satisfies the first four fields, the user is granted membership
of the listed groups.

<p>
As stated in above 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 <em/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 <em/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
<em/nosuid/.

<p>
The <tt>pam_group</tt> module fuctions in parallel with the
<tt>/etc/group</tt> file. If the user is granted any groups based on
the behavior of this module, they are granted <em>in addition</em> to
those entries <tt>/etc/group</tt> (or equivalent).

</descrip>

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