  The LLiinnuuxx--PPAAMM System Administrators' guide
  Andrew G. Morgan, mmoorrggaann@@pphhyyssiiccss..uuccllaa..eedduu
  DRAFT v0.2 1996/3/6

  This manual documents what a system-administrator needs to know about
  the LLiinnuuxx--PPAAMM library. It covers the correct syntax of the PAM config-
  uration file and discusses strategies for maintaining a secure system.
  ______________________________________________________________________

  Table of Contents:

  1.      Introduction

  2.      The Linux-PAM configuration file

  3.      Security issues of Linux-PAM

  4.      An example

  5.      Files

  6.      See also

  7.      Notes

  8.      Author/acknowledgments

  9.      Bugs/omissions
  ______________________________________________________________________

  11..  IInnttrroodduuccttiioonn

  LLiinnuuxx--PPAAMM (Pluggable Authentication Modules for Linux) is a suite of
  shared libraries that enable the local system administrator to choose
  how applications authenticate users.

  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.

  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 /etc/passwd file).
  On such systems, most if not all forms of privileges are granted based
  on this single authentication scheme.

  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 facts, new methods of authentication are continuously
  being developed.

  It is the purpose of the LLiinnuuxx--PPAAMM 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, //eettcc//ppaamm..ccoonnff, to authenticate a user request via the
  locally available authentication modules. The modules themselves will
  usually be located in the directory //uussrr//lliibb//sseeccuurriittyy and take the
  form of dynamically loadable object files (see dlopen(3)).

  22..  TThhee LLiinnuuxx--PPAAMM ccoonnffiigguurraattiioonn ffiillee

  This section will discuss the need for, and syntax of, the
  //eettcc//ppaamm..ccoonnff file.

  Note, the LLiinnuuxx--PPAAMM specific tokens in this file are case _i_n_s_e_n_s_i_t_i_v_e.
  The mmoodduullee__ppaatthhs are case sensitive, since they indicate a file's
  _n_a_m_e. The case-sensitivity of the arguments to any given module is
  defined for each module in turn.

  more needed...

  33..  SSeeccuurriittyy iissssuueess ooff LLiinnuuxx--PPAAMM

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

  Perhaps it needs a list of the currently available LLiinnuuxx--PPAAMM modules
  and a brief description of what they do?

  44..  AAnn eexxaammppllee //eettcc//ppaamm..ccoonnff file

  _I _t_h_i_n_k _t_h_e_r_e _s_h_o_u_l_d _b_e _a _s_e_c_u_r_e_(_i_s_h_) _b_l_a_n_k _p_a_m_._c_o_n_f _f_i_l_e _s_o_m_e_w_h_e_r_e _i_n
  _t_h_e _d_i_s_t_r_i_b_u_t_i_o_n_. _I_n _c_a_s_e _t_h_e _s_y_s_-_a_d_m_i_n _m_a_n_g_l_e_s _t_h_e_i_r_s_. _I_f _i_t _i_s _n_o_t
  _t_o_o _l_o_n_g _i_t _c_o_u_l_d _b_e _g_i_v_e_n _h_e_r_e_, _o_t_h_e_r_w_i_s_e _w_e _c_a_n _j_u_s_t _p_o_i_n_t _t_o _i_t_.

  55..  FFiilleess

     //eettcc//ppaamm..ccoonnff
        the LLiinnuuxx--PPAAMM configuration file

     //uussrr//lliibb//sseeccuurriittyy//ppaamm__**__**..ssoo
        Authentication modules.

  66..  SSeeee aallssoo

  +o  The LLiinnuuxx--PPAAMM application writers' guide; pam_appl.html.

  +o  The LLiinnuuxx--PPAAMM module writers' guide pam_modules.html.

  +o  The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH
     PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation
     Request For Comments 86.0, October 1995.

  77..  NNootteess

  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! :)

  88..  AAuutthhoorr//aacckknnoowwlleeddggmmeennttss

  This manual was written by Andrew Morgan (morgan@physics.ucla.edu)
  with many contributions from Marc Ewing, Marek Mickalchiewicz,
  Theodore Ts'o and Jeoff Uphoff.

  Thanks are also due to Sun Microsystems. At an early stage in the
  development of LLiinnuuxx--PPAAMM, Sun graciously made the documentation for
  their implementation of PAM availible. This act greatly accelerated
  the developement of LLiinnuuxx--PPAAMM.

  99..  BBuuggss//oommiissssiioonnss

  No PAM modules currently exist. No 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.

