<!doctype linuxdoc system>

<!--

 $Id: pam.sgml,v 1.8 1996/06/02 07:54:21 morgan Exp $

    Copyright (C) Andrew G. Morgan 1996.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

1. Redistributions of source code must retain the above copyright
   notice, and the entire permission notice in its entirety,
   including the disclaimer of warranties.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

3. The name of the author may not be used to endorse or promote
   products derived from this software without specific prior
   written permission.

ALTERNATIVELY, this product may be distributed under the terms of the
GNU General Public License, in which case the provisions of the GNU
GPL are required INSTEAD OF the above restrictions.  (This clause is
necessary due to a potential bad interaction between the GNU GPL and
the restrictions contained in a BSD-style copyright.)

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.

 -->

<article>

<title>The <bf/Linux-PAM/ System Administrators' Guide
<author>Andrew G. Morgan, <tt>morgan@physics.ucla.edu</tt>
<date>DRAFT v0.42 1996/5/31
<abstract>
This manual documents what a system-administrator needs to know about
the <bf>Linux-PAM</bf> library. It covers the correct syntax of the
PAM configuration file and discusses strategies for maintaining a
secure system.
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<sect>Introduction


<p><bf/Linux-PAM/ (Pluggable Authentication Modules for Linux) is a
suite of shared libraries that enable the local system administrator
to choose how applications authenticate users.

<p>In other words, without (rewriting and) recompiling a PAM-aware
application, it is possible to switch between the authentication
mechanism(s) it uses. Indeed, one may entirely upgrade the local
authentication system without touching the applications themselves.

<p>Historically an application that has required a given user to be
authenticated, has had to be compiled to use a specific authentication
mechanism.  For example, in the case of traditional UN*X systems, the
identity of the user is verified by the user entering a correct
password.  This password, after being prefixed by a two character
``salt'', is encrypted (with crypt(3)). The user is then authenticated
if this encrypted password is identical to the second field of the
user's entry in the system password database (the <tt>/etc/passwd</tt>
file).  On such systems, most if not all forms of privileges are
granted based on this single authentication scheme. Privilege comes in
the form of a personal user-identifier (<tt/uid/) and membership of
various groups. Services and applications are available based on the
personal and group identity of the user. Traditionally, group
membership has been assigned based on entries in the
<tt>/etc/group</tt> file.

<p>
Unfortunately, increases in the speed of computers and the
widespread introduction of network based computing, have made once
secure authentication mechanisms, such as this, vulnerable to
attack. In the light of such realities, new methods of authentication
are continuously being developed.

<p>
It is the purpose of the <bf/Linux-PAM/ project to separate the
development of privilege granting software from the development of
secure and appropriate authentication schemes.  This is accomplished
by providing a library of functions that an application may use to
request that a user be authenticated. This PAM library is configured
locally with a system file, <tt>/etc/pam.conf</tt>, to authenticate a
user request via the locally available authentication modules. The
modules themselves will usually be located in the directory
<tt>/usr/lib/security</tt> and take the form of dynamically loadable
object files (see <tt/dlopen(3)/).

<p>
Here is a figure that describes the overall organization of
<bf/Linux-PAM/.
<tscreen>
<verb>
	 +----------------+
	 | application: X |
         +----------------+	  /  +----------+     +================+
       	 | authentication-[---->--\--] Linux-   |--<--| /etc/pam.conf  |
	 |       +        [----<--/--] 	 PAM    |     |================|
	 |[conversation()][--+    \  |          |     | X auth .. a.so |
	 +----------------+  |    /  +-n--n-----+     | X auth .. b.so |
	 |                |  |       __|  |           |           _____/
	 |  service user  |  A      |  	  |           |____,-----' 
	 |                |  |      V  	  A	        	   
	 +----------------+  +------|-----|---------+ -----+------+
	                        +---u-----u----+    |	   |	  |
			        |   auth....   |--[ a ]--[ b ]--[ c ]
				+--------------+
				|   acct....   |--[ b ]--[ d ]
				+--------------+
				|   password   |--[ b ]--[ c ]
				+--------------+
				|   session    |--[ e ]--[ c ]
				+--------------+
</verb>
</tscreen>

<sect>The Linux-PAM configuration file

<p>
<bf/Linux-PAM/ is designed to provide the system administrator with a
great deal of flexibility in configuring the privilege granting
applications of their system. The local configuration of those aspects
of system security controlled by <tt/Linux-PAM/ is contained in the
system file, <tt>/etc/pam.conf</tt>.  In this section we discuss the
correct syntax of and generic options respected by entries to this
file.

<sect1>File syntax

<p>
The reader should note that the <bf/Linux-PAM/ specific tokens in this
file are case <em/insensitive/. The module paths, however, are case
sensitive since they indicate a file's <em/name/ and reflect the case
dependence of typical Linux file-systems. The case-sensitivity of the
arguments to any given module is defined for each module in turn.

<p>
In addition to the lines described below, there are two <em/special/
characters provided for the convenience of the system administrator:
comments are preceded by a `<tt/&num;/', the comment extending to the
next end of line; also, module specification lines may be extended
with a `<tt/&bsol;/'.

<p>
A general configuration line the the <tt>/etc/pam.conf</tt> file has
the following form:
<tscreen>
<verb>
service-name   module-type   control-flag   module-path   arguments
</verb>
</tscreen>
Here we explain the meaning of each of these tokens.

<p>
<descrip>
<tag><tt/service-name/</tag>
The name of the service associated with this entry. Frequently the
service name is the conventional name of the given application. For
example, `<tt/ftpd/', `<tt/rlogind/' and `<tt/su/', <em/etc./ .

<p>
There is a special <tt/service-name/, reserved for defining a default
authentication mechanism. It has the name `<tt/OTHER/' and may be
specified in either lower or upper case characters.

<tag><tt/module-type/</tag>
One of (currently) four types of module. The four types are as
follows:
<itemize>
<item> <tt/auth/; this module type provides two aspects of
authenticating the user. Firstly, it establishes that the user is who
they claim to be, by instructing the application to prompt the user
for a password or other means of identification. Secondly, the module
can grant <tt/group/ membership (independently of the
<tt>/etc/groups</tt> file discussed above) or other privileges through
its <em/credential/ granting properties.

<item> <tt/account/; this module performs non-authentication based
account management. It is typically used to restrict/permit access to
a service based on the time of day, currently available system
resources (maximum number of users) or perhaps the location of the
applicant user---`<tt/root/' login only on the console.

<item> <tt/session/; primarily, this module is associated with logging
information concerning the opening/closing of some data exchange with
a user. It is intended for auditing purposes and is likely to be
indispensable for maintaining a secure Linux system.

<item> <tt/password/; this last module type is required for updating the
authentication token associated with the user. Typically, there is one
module for each `challenge/response' based authentication (<tt/auth/)
module-type.

</itemize>

<tag><tt/control-flag/</tag>

One of (currently) three tokens that indicate the severity of
concern associated with the success or failure of a given module.
<bf/Linux-PAM/ provides for the <em/stacking/ of similar modules,
providing a method of simultaneously exposing the user to more than
one authentication mechanism.  The application is not made aware of
the individual success or failure of modules listed in the
`<tt>/etc/pam.conf</tt>' file. Instead, it receives a summary
<em/success/ or <em/fail/ response from the <bf/Linux-PAM/
library. The order of execution of these modules is that of the
entries in the <tt>/etc/pam.conf</tt> file; earlier entries are
executed before later ones.

<p>
The policy for determining this response is based on these
three <tt/control-flag/s:

<itemize>

<item> <tt/required/; this indicates that the success of the module is
required for the <tt/module-type/ facility to succeed. Failure of this
module will not be apparent to the user until all of the remaining
modules (of the same <tt/module-type/) have been executed.

<item> <tt/sufficient/; the success of this module is deemed
`<em/sufficient/' to satisfy the <bf/Linux-PAM/ library that this
module-type has succeeded in its purpose. In the event that no
previous <tt/required/ module has failed, no more `<em/stacked/'
modules of this type are invoked. (Note, in this case subsequent
<tt/required/ modules are <bf/not/ invoked.). A failure of this module
is not deemed as fatal to satisfying the application that this
<tt/module-type/ has succeeded.

<item> <tt/optional/; as its name suggests, this <tt/control-flag/
marks the module as not being critical to the success or failure of
the user's application for service. However, in the absence of any
successes of previous or subsequent stacked modules this module will
determine the nature of the response to the application.

</itemize>

<tag> <tt/module-path/</tag>

The path-name of the dynamically loadable object file; <em/the
pluggable module/ itself.

<tag> <tt/args/</tag>

The <tt/args/ are a list of tokens that are passed to the module when
it is invoked. Much like arguments to a typical Linux shell command.
Generally, valid arguments are optional and are specific to any given
module. Invalid arguments are ignored by a module, however, when
encountering an invalid argument, the module is required to write an
error to <tt/syslog(2)/. For a list of <em/generic/ options see the
next section.

</descrip>

<p>
Any line, in <tt>/etc/pam.conf</tt>, that is not formatted correctly
is ignored by <bf/Linux-PAM/; however, a corresponding error is
written to the system log files with a call to <tt/syslog(2)/.

<sect1>Generic optional arguments

<p>
The following are optional arguments which are likely to be understood
by any module. Arguments (including these) are in general
<em/optional/.

<p>
<descrip>
<tag><tt/debug/</tag>

Use the <tt/syslog(2)/ call to log debugging information to the system
log files.

<tag> <tt/no_warn/</tag>

Instruct module to not give warning messages to the application.

<tag> <tt/use_first_pass/</tag>

The module should not prompt the user for a password. Instead, it
should obtain the previously typed password (from the preceding
<tt/auth/ module), and use that. If that doesn't work, then the user
will not be authenticated. (This option is intended for <tt/auth/
and <tt/password/ modules only).

<tag> <tt/try_first_pass/</tag>

The module should attempt authentication with the previously typed
password (from the preceding <tt/auth/ module). If that doesn't work,
then the user is prompted for a password. (This option is intended for
<tt/auth/ modules only).

<tag> <tt/use_mapped_pass/</tag>

This argument is not currently supported by any of the modules in the
<bf/Linux-PAM/ distribution because of possible consequences
associated with U.S. encryption exporting restrictions. Within the
U.S., module developers are, of course, free to implement it (as are
developers in other countries). For compatibility reasons we describe
its use as suggested in the <bf/DCE-RFC 86.0/, see the section <ref
id="see-also-sec" name="bibliography"> for a pointer to this document.

<p>
The <tt/use_mapped_pass/ argument instructs the module to take the
clear text authentication token entered by a previous module (that
requests such a token) and use it to generate an encryption/decryption
key with which to safely store/retrieve the authentication token
required for this module. In this way the user can enter a single
authentication token and be quietly authenticated by a number of
stacked modules.  Obviously a convenient feature that necessarily
requires some reliably strong encryption to make it secure.
This argument is intended for the <tt/auth/ and <tt/password/ module
types only.

</descrip>

<sect>Security issues of Linux-PAM

<p>
This section will discuss good practices for constructing a secure
pam.conf file.

<p>
Perhaps it needs a list of the currently available <bf/Linux-PAM/
modules and a brief description of what they do?

<p>
It is not a good thing to have a weak default (<tt/OTHER/) entry.

<sect>An example <tt>/etc/pam.conf</tt> file

<p><em>
I think there should be a secure(ish) blank pam.conf file somewhere in
the distribution. In case the sys-admin mangles theirs. If it is not
too long it could be given here, otherwise we can just point to it.
</em>

<p> Is this too simple?
<tscreen>
<verb>
#
# default; deny access
#

OTHER	auth	 required	/usr/lib/security/pam_deny.so
OTHER	account	 required	/usr/lib/security/pam_deny.so
OTHER	password required	/usr/lib/security/pam_deny.so
OTHER	session	 required	/usr/lib/security/pam_deny.so
</verb>
</tscreen>

<sect>Files

<p><descrip>

<tag><tt>/usr/lib/libpam.so.*</tt></tag>

the shared library providing applications with access to
<bf/Linux-PAM/.

<tag><tt>/etc/pam.conf</tt></tag>

the <bf/Linux-PAM/ configuration file.

<tag><tt>/usr/lib/security/pam_*.so</tt></tag>

the primary location for <bf/Linux-PAM/ dynamically loadable object
files; the modules.

</descrip>

<sect>See also<label id="see-also-sec">

<p><itemize>

<item>The <bf/Linux-PAM/ Application Writers' Guide.

<item>The <bf/Linux-PAM/ Module Writers' Guide.

<item>The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH
PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation Request
For Comments 86.0, October 1995. See this url:
<tt><htmlurl
url="http://www.pilgrim.umass.edu/pub/osf_dce/RFC/rfc86.0.txt"
name="http://www.pilgrim.umass.edu/pub/osf&lowbar;dce/RFC/rfc86.0.txt"></tt>

</itemize>

<sect>Notes

<p>
I intend to put development comments here... like ``at the moment
this isn't actually supported''. At release time what ever is in
this section will be placed in the Bugs section below! :)

<p>
Are we going to be able to support the <tt/use_mapped_pass/ module
argument? Anyone know a cheap (free) good lawyer?!

<sect>Author/acknowledgments

<p>
This document was written by Andrew G. Morgan
(morgan@physics.ucla.edu) with many contributions from Marc Ewing,
Michael K. Johnson, Al Longyear, Marek Michalkiewicz, Theodore Ts'o,
Jeff Uphoff, Joseph S. D. Yao and Alex O.  Yuriev.

<p>
Thanks are also due to Sun Microsystems, especially to Vipin Samar and
Charlie Lai for their advice. At an early stage in the development of
<bf/Linux-PAM/, Sun graciously made the documentation for their
implementation of PAM available. This act greatly accelerated the
development of <bf/Linux-PAM/.

<sect>Bugs/omissions

<p>Few PAM modules currently exist. Few PAM-aware applications exist.
This manual is hopelessly unfinished. Only a partial list of people is
credited for all the good work they have done.

</article>
