New upstream version 0.76

1 files changed, 369 insertions, 0 deletions

diff --git a/Linux-PAM/doc/man/pam.8 b/Linux-PAM/doc/man/pam.8
new file mode 100644
index 00000000..f2ef9c1f
--- /dev/null
+++ b/Linux-PAM/doc/man/pam.8
@@ -0,0 +1,369 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\" $Id: pam.8,v 1.1.1.1 2001/04/29 04:16:52 hartmans Exp $
+.\" Copyright (c) Andrew G. Morgan 1996-7,2001 <morgan@kernel.org>
+.TH PAM 8 "2001 Jan 20" "Linux-PAM 0.74" "Linux-PAM Manual"
+.SH NAME
+
+Linux-PAM \- Pluggable Authentication Modules for Linux
+
+.SH SYNOPSIS
+.B /etc/pam.conf
+.sp 2
+.SH DESCRIPTION
+
+This manual is intended to offer a quick introduction to
+.BR Linux-PAM ". "
+For more information the reader is directed to the
+.BR "Linux-PAM system administrators' guide".
+
+.sp
+.BR Linux-PAM
+Is a system of libraries that handle the authentication tasks of
+applications (services) on the system.  The library provides a stable
+general interface (Application Programming Interface - API) that
+privilege granting programs (such as
+.BR login "(1) "
+and
+.BR su "(1)) "
+defer to to perform standard authentication tasks.
+
+.sp
+The principal feature of the PAM approach is that the nature of the
+authentication is dynamically configurable.  In other words, the
+system administrator is free to choose how individual
+service-providing applications will authenticate users. This dynamic
+configuration is set by the contents of the single
+.BR Linux-PAM
+configuration file
+.BR /etc/pam.conf "."
+Alternatively, the configuration can be set by individual
+configuration files located in the
+.B /etc/pam.d/
+directory.
+.IB "The presence of this directory will cause " Linux-PAM " to ignore"
+.BI /etc/pam.conf "."
+
+.sp
+From the point of view of the system administrator, for whom this
+manual is provided, it is not of primary importance to understand the
+internal behavior of the
+.BR Linux-PAM
+library.  The important point to recognize is that the configuration
+file(s)
+.I define
+the connection between applications
+.BR "" "(" services ")"
+and the pluggable authentication modules
+.BR "" "(" PAM "s)"
+that perform the actual authentication tasks.
+
+.sp
+.BR Linux-PAM
+separates the tasks of
+.I authentication
+into four independent management groups:
+.BR "account" " management; "
+.BR "auth" "entication management; "
+.BR "password" " management; "
+and
+.BR "session" " management."
+(We highlight the abbreviations used for these groups in the
+configuration file.)
+
+.sp
+Simply put, these groups take care of different aspects of a typical
+user's request for a restricted service:
+
+.sp
+.BR account " - "
+provide account verification types of service: has the user's password
+expired?; is this user permitted access to the requested service?
+
+.br
+.BR auth "entication - "
+establish the user is who they claim to be. Typically this is via some
+challenge-response request that the user must satisfy: if you are who
+you claim to be please enter your password.  Not all authentications
+are of this type, there exist hardware based authentication schemes
+(such as the use of smart-cards and biometric devices), with suitable
+modules, these may be substituted seamlessly for more standard
+approaches to authentication - such is the flexibility of
+.BR Linux-PAM "."
+
+.br
+.BR password " - "
+this group's responsibility is the task of updating authentication
+mechanisms. Typically, such services are strongly coupled to those of
+the
+.BR auth
+group. Some authentication mechanisms lend themselves well to being
+updated with such a function. Standard UN*X password-based access is
+the obvious example: please enter a replacement password.
+
+.br
+.BR session " - "
+this group of tasks cover things that should be done prior to a
+service being given and after it is withdrawn. Such tasks include the
+maintenance of audit trails and the mounting of the user's home
+directory. The
+.BR session
+management group is important as it provides both an opening and
+closing hook for modules to affect the services available to a user.
+
+.SH The configuration file(s)
+
+When a
+.BR Linux-PAM
+aware privilege granting application is started, it activates its
+attachment to the PAM-API.  This activation performs a number of
+tasks, the most important being the reading of the configuration file(s):
+.BR /etc/pam.conf "."
+Alternatively, this may be the contents of the
+.BR /etc/pam.d/
+directory.
+
+These files list the
+.BR PAM "s"
+that will do the authentication tasks required by this service, and
+the appropriate behavior of the PAM-API in the event that individual
+.BR PAM "s "
+fail.
+
+.sp
+The syntax of the
+.B /etc/pam.conf
+configuration file is as follows. The file is made
+up of a list of rules, each rule is typically placed on a single line,
+but may be extended with an escaped end of line: `\\<LF>'. Comments
+are preceded with `#' marks and extend to the next end of line.
+
+.sp
+The format of each rule is a space separated collection of tokens, the
+first three being case-insensitive:
+
+.sp
+.br
+.BR "   service  type  control  module-path  module-arguments"
+
+.sp
+The syntax of files contained in the
+.B /etc/pam.d/
+directory, are identical except for the absence of any
+.I service 
+field. In this case, the
+.I service
+is the name of the file in the
+.B /etc/pam.d/
+directory. This filename must be in lower case.
+
+.sp
+An important feature of
+.BR Linux-PAM ", "
+is that a number of rules may be
+.I stacked
+to combine the services of a number of PAMs for a given authentication
+task.
+
+.sp
+The
+.BR service
+is typically the familiar name of the corresponding application:
+.BR login
+and 
+.BR su
+are good examples. The
+.BR service "-name, " other ", "
+is reserved for giving
+.I default
+rules.  Only lines that mention the current service (or in the absence
+of such, the
+.BR other
+entries) will be associated with the given service-application.
+
+.sp
+The
+.BR type
+is the management group that the rule corresponds to. It is used to
+specify which of the management groups the subsequent module is to
+be associated with. Valid entries are:
+.BR account "; "
+.BR auth "; "
+.BR password "; "
+and
+.BR session "."
+The meaning of each of these tokens was explained above.
+
+.sp
+The third field,
+.BR control ", "
+indicates the behavior of the PAM-API should the module fail to
+succeed in its authentication task. There are two types of syntax for
+this control field: the simple one has a single simple keyword; the
+more complicated one involves a square-bracketed selection of
+.B value=action
+pairs.
+
+.sp
+For the simple (historical) syntax valid
+.BR control
+values are:
+.BR requisite
+- failure of such a PAM results in the immediate termination of the
+authentication process;
+.BR required
+- failure of such a PAM will ultimately lead to the PAM-API returning
+failure but only after the remaining
+.I stacked
+modules (for this
+.BR service
+and
+.BR type ")"
+have been invoked;
+.BR sufficient
+- success of such a module is enough to satisfy the authentication
+requirements of the stack of modules (if a prior
+.BR required
+module has failed the success of this one is
+.IR ignored "); "
+.BR optional
+- the success or failure of this module is only important if it is the
+only module in the stack associated with this
+.BR service "+" type "."
+
+.sp
+For the more complicated syntax valid
+.B control
+values have the following form:
+.sp
+.RB  [value1=action1 value2=action2 ...]
+.sp
+Where
+.B valueN
+corresponds to the return code from the function invoked in the module
+for which the line is defined. It is selected from one of these:
+.BR success ;
+.BR open_err ;
+.BR symbol_err ;
+.BR service_err ;
+.BR system_err ;
+.BR buf_err ;
+.BR perm_denied ;
+.BR auth_err ;
+.BR cred_insufficient ;
+.BR authinfo_unavail ;
+.BR user_unknown ;
+.BR maxtries ;
+.BR new_authtok_reqd ;
+.BR acct_expired ;
+.BR session_err ;
+.BR cred_unavail ;
+.BR cred_expired ;
+.BR cred_err ;
+.BR no_module_data ;
+.BR conv_err ;
+.BR authtok_err ;
+.BR authtok_recover_err ;
+.BR authtok_lock_busy ;
+.BR authtok_disable_aging ;
+.BR try_again ;
+.BR ignore ;
+.BR abort ;
+.BR authtok_expired ;
+.BR module_unknown ;
+.BR bad_item "; and"
+.BR default .
+The last of these,
+.BR default ,
+implies 'all
+.BR valueN 's
+not mentioned explicitly. Note, the full list of PAM errors is
+available in /usr/include/security/_pam_types.h . The
+.B actionN
+can be: an unsigned integer, 
+.BR J ,
+signifying an action of 'jump over the next J modules in the stack';
+or take one of the following forms:
+.br
+.B ignore
+- when used with a stack of modules, the module's return status will
+not contribute to the return code the application obtains;
+.br
+.B bad 
+- this action indicates that the return code should be thought of as
+indicative of the module failing. If this module is the first in the
+stack to fail, its status value will be used for that of the whole
+stack.
+.br
+.B die
+- equivalent to bad with the side effect of terminating the module
+stack and PAM immediately returning to the application.
+.br
+.B ok
+- this tells PAM that the administrator thinks this return code
+should contribute directly to the return code of the full stack of
+modules. In other words, if the former state of the stack would lead
+to a return of
+.BR PAM_SUCCESS ,
+the module's return code will override this value. Note, if the former
+state of the stack holds some value that is indicative of a modules
+failure, this 'ok' value will not be used to override that value.
+.br
+.B done
+- equivalent to ok with the side effect of terminating the module
+stack and PAM immediately returning to the application.
+.br
+.B reset
+- clear all memory of the state of the module stack and start again
+with the next stacked module.
+
+.sp
+.BR module-path
+- this is either the full filename of the PAM to be used by the
+application (it begins with a '/'), or a relative pathname from the
+default module location:
+.BR /lib/security/ .
+
+.sp
+.BR module-arguments
+- these are a space separated list of tokens that can be used to
+modify the specific behavior of the given PAM. Such arguments will be
+documented for each individual module.
+
+.SH "FILES"
+.BR /etc/pam.conf " - the configuration file"
+.br
+.BR /etc/pam.d/ " - the"
+.BR Linux-PAM
+configuration directory. Generally, if this directory is present, the
+.B /etc/pam.conf
+file is ignored.
+.br
+.BR /lib/libpam.so.X " - the dynamic library"
+.br
+.BR /lib/security/*.so " - the PAMs
+
+.SH ERRORS
+Typically errors generated by the
+.BR Linux-PAM
+system of libraries, will be written to
+.BR syslog "(3)."
+
+.SH "CONFORMING TO"
+DCE-RFC 86.0, October 1995.
+.br
+Contains additional features, but remains backwardly compatible with
+this RFC.
+
+.SH BUGS
+.sp 2
+None known.
+
+.SH "SEE ALSO"
+
+The three
+.BR Linux-PAM
+Guides, for
+.BR "system administrators" ", "
+.BR "module developers" ", "
+and
+.BR "application developers" ". "