  The LLiinnuuxx--PPAAMM Module writers' 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 programmer needs to know in order to
  write a module that conforms to the LLiinnuuxx--PPAAMM standard. It also dis-
  cusses some security issues from the point of view of the module pro-
  grammer.

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

  11..11..  SSYYNNOOPPSSIISS

       #include <security/pam_modules.h>

       ??? cc -fPIC -o pam_module-name.so .... -lpam

  11..22..  DDeessccrriippttiioonn

  LLiinnuuxx--PPAAMM (Pluggable Authentication Modules for Linux) is a library
  that enables the local system administrator to choose how individual
  applications authenticate users.  For an overview of the LLiinnuuxx--PPAAMM
  library see ppaamm((55)).

  A LLiinnuuxx--PPAAMM module is a single executable binary file that can be
  loaded by the pam interface library. 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)).  It is the PAM interface that is called by an application
  and it is the responsibility of the library to load and call functions
  in a PAM-module.

  Except for the immediate purpose of interacting with the user
  (entering a password etc..) the module should never call the
  application directly. This exception requires a "conversation
  mechanism" which is documented below.

  22..  TThhee ppuubblliicc iinntteerrffaaccee ttoo aa mmoodduullee

  Here we list the interface that the conventions that all LLiinnuuxx--PPAAMM
  modules must adhere to.

  22..11..  WWhhaatt ccaann bbee eexxppeecctteedd bbyy tthhee mmoodduullee

  First, we cover what the module should expect from the Linux-PAM
  library and a PAM-aware application.

  +o  eexxtteerrnn iinntt ppaamm__sseett__ddaattaa((ppaamm__hhaannddllee__tt **ppaammhh,, ccoonnsstt cchhaarr
     **mmoodduullee__ddaattaa__nnaammee,, ccoonnsstt vvooiidd **ddaattaa,, iinntt ((**cclleeaannuupp))((ppaamm__hhaannddllee__tt
     **ppaammhh,, ccoonnsstt vvooiidd **ddaattaa,, iinntt eerrrroorr__ssttaattuuss))));;

     The modules are dynamically loadable modules. In general such files
     should not contain _s_t_a_t_i_c variables. This and the subsequent
     function provide a mechanism for a module to associate some data
     with the handle ppaammhh. Typically a module will call the ppaamm__sseett__ddaattaa
     function to register some data under a (hopefully) unique
     mmoodduullee__ddaattaa__nnaammee. The data is availible for use by other modules
     too but _n_o_t by an application.  XXX - see notes

     The function cclleeaannuupp is associated with the ddaattaa and, if non-NNUULLLL,
     it is called when this data is over-written or following a call to
     ppaamm__eenndd (see pam_appl.html).

  +o  eexxtteerrnn iinntt ppaamm__ggeett__ddaattaa((ccoonnsstt ppaamm__hhaannddllee__tt **ppaammhh,, ccoonnsstt cchhaarr
     **mmoodduullee__ddaattaa__nnaammee,, ccoonnsstt vvooiidd ****ddaattaa));;

     This function together with the previous one provides a method of
     associating module-specific data with the handle ppaammhh. A successful
     call to ppaamm__ggeett__ddaattaa will result in **ddaattaa pointing to the data
     associated with the mmoodduullee__ddaattaa__nnaammee. Note, this data is nnoott a copy
     and should be treated as ccoonnssttaanntt by the module.

  +o  eexxtteerrnn iinntt ppaamm__sseett__iitteemm((ppaamm__hhaannddllee__tt **ppaammhh,, iinntt iitteemm__ttyyppee,, ccoonnsstt
     vvooiidd **iitteemm));;

     This function is used to (re)set the value of one of the
     iitteemm__ttyyppees.  The reader is urged to read the entry for this
     function in the Linux-PAM application developers' manual,
     pam_appl.html.

     In addition to the iitteemms listed there, the module can set the
     following two iitteemm__ttppyyees:

     PPAAMM__AAUUTTHHTTOOKK
        The authentication token (password)  XXX - see notes

     PPAAMM__OOLLDDAAUUTTHHTTOOKK
        The old authentication token  XXX - see notes

  +o  eexxtteerrnn iinntt ppaamm__ggeett__iitteemm((ccoonnsstt ppaamm__hhaannddllee__tt **ppaammhh,, iinntt iitteemm__ttyyppee,,
     vvooiidd ****iitteemm));;

     This function is used to obtain the value of the specified
     iitteemm__ttyyppee. It is better documented in the LLiinnuuxx--PPAAMM application
     developers' manual, pam_appl.html. However, the module is
     additionally privileged to read the above authentication tokens
     (PPAAMM__AAUUTTHHTTOOKK and PPAAMM__OOLLDDAAUUTTHHTTOOKK). Note it is required that these
     tokens are made NNUULLLL before process control passes back to the
     application.

     Following the call ppaamm__ggeett__iitteemm((ppaammhh,,PPAAMM__CCOONNVV,,&&iitteemm)), the pointer
     iitteemm points to a _c_o_n_v_e_r_s_a_t_i_o_n-function that provides limited but
     direct access to the application.  The purpose of this function is
     to allow the module to prompt the user for their password pass
     other information in a manner consistent with the application. For
     example, an X-windows based program might pop up a dialog box to
     report a login failure. Just as the application should not be
     concerned with the method of authentication, so the module should
     not dictate the manner in which input/output is obtained/presented
     to the user.

     The reader might care to read the description of the ppaamm__ccoonnvv
     structure, written from the perspective of the application
     developer in pam_appl.html.

     The ppaamm__rreessppoonnssee structure returned after a call to the ppaamm__ccoonnvv
     function must be ffrreeee(())'d by the module. Since the call to the
     conversation function originates from the module, it is clear that
     either this ppaamm__rreessppoonnssee structure is statically or dynamically
     (using mmaalllloocc(()) etc.) allocated within the application. Repeated
     calls to the conversation function would likely overwrite static
     memory, so it is required that for a successful return from the
     conversation function the memory for the response structure is
     dynamically allocated by the application with one of the mmaalllloocc(())
     family of commands and _m_u_s_t be ffrreeee(())'d by the module.

  +o  eexxtteerrnn iinntt ppaamm__ggeett__uusseerr((ppaamm__hhaannddllee__tt **ppaammhh,, ));;

  +o  eexxtteerrnn ccoonnsstt cchhaarr **ppaamm__ssttrreerrrroorr((iinntt eerrrrnnuumm));;

     This function returns some text describing the LLiinnuuxx--PPAAMM error
     associated with the argument eerrrrnnuumm.  XXX - see notes

  33..  WWhhaatt iiss eexxppeecctteedd ooff aa mmoodduullee

  The module must supply the functions listed below. Together they
  define the function of a LLiinnuuxx--PPAAMM mmoodduullee. Module developers are
  strongly urged to read the comments on security that follow this list.

  Note, each of the following functions mmuusstt be defined in all modules.
  If a module developer does not want a specific one of these functions
  to be used, it should be defined to simply return PPAAMM__IIGGNNOORREE.

  +o  eexxtteerrnn iinntt ppaamm__ssmm__aauutthheennttiiccaattee((ppaamm__hhaannddllee__tt **ppaammhh,, iinntt ffllaaggss,, iinntt
     aarrggcc,, ccoonnsstt cchhaarr ****aarrggvv));;

     This function performs the task of authenticating the user. The
     aarrggcc and aarrggvv arguments are taken from the line appropriate to this
     module---that is with a _m_o_d_u_l_e___t_y_p_e of aauutthh---in the configuration
     file (see ppaamm((55))). Together these arguments provide the number of
     arguments and an array of pointers to the individual argument
     tokens. This will be familiar to C programmers as the ubiquitous
     method of passing command arguments to the function mmaaiinn(()).

     The ffllaaggss argument can be a logically OR'd combination of the
     following:

     PPAAMM__SSIILLEENNTT
        do not generate any text (errors or otherwise),

     PPAAMM__DDIISSAALLLLOOWW__NNUULLLL__AAUUTTHHTTOOKK
        return PPAAMM__AAUUTTHH__EERRRROORR if the database of authentication tokens
        for this authentication mechanism has a NNUULLLL entry for the user.
        Without this flag, such a NNUULLLL token will lead to a success
        without the user being prompted.

     If the module authorization is un-sucessful, it will return
     PPAAMM__AAUUTTHH__EERRRR. The application my susequently retry the
     authentication procedure. However, if the module returns
     PPAAMM__MMAAXXTTRRIIEESS, the application should not attempt to retry user
     authentication.

     Other valid responses of this function are:

     PPAAMM__CCRREEDD__IINNSSUUFFFFIICCIIEENNTT
        User does not have sufficient credentials to be authenticated.

     PPAAMM__AAUUTTHHIINNFFOO__UUNNAAVVAAIILL
        Module is unable to get authentication information.

     PPAAMM__UUSSEERR__UUNNKKNNOOWWNN
        The module can find no record of the user.

  +o  iinntt ppaamm__ssmm__sseettccrreedd((ppaamm__hhaannddllee__tt **ppaammhh,, iinntt ffllaaggss,, iinntt aarrggcc,, ccoonnsstt
     cchhaarr ****aarrggvv));;

     This function performs the task of altering the credentials of the
     user with respect to the corresponding authorization scheme.
     Generally, an authentication module may have access to more
     information about a user than their authentication token. This
     function is used to ammend such information. Ordinarily, it is
     called _a_f_t_e_r the user has been authenticated.

  +o  eexxtteerrnn iinntt ppaamm__ssmm__aacccctt__mmggmmtt((ppaamm__hhaannddllee__tt **ppaammhh,, iinntt ffllaaggss,, iinntt
     aarrggcc,, ccoonnsstt cchhaarr ****aarrggvv));;

  +o  eexxtteerrnn iinntt ppaamm__ssmm__ooppeenn__sseessssiioonn((ppaamm__hhaannddllee__tt **ppaammhh,, iinntt ffllaaggss,, iinntt
     aarrggcc,, ccoonnsstt cchhaarr ****aarrggvv));;

  +o  eexxtteerrnn iinntt ppaamm__ssmm__cclloossee__sseessssiioonn((ppaamm__hhaannddllee__tt **ppaammhh,, iinntt ffllaaggss,, iinntt
     aarrggcc,, ccoonnsstt cchhaarr ****aarrggvv));;

  +o  eexxtteerrnn iinntt ppaamm__ssmm__cchhaauutthhttookk((ppaamm__hhaannddllee__tt **ppaammhh,, iinntt ffllaaggss,, iinntt
     aarrggcc,, ccoonnsstt cchhaarr ****aarrggvv));;

  44..  SSeeccuurriittyy iissssuueess ffoorr mmoodduullee ccrreeaattiioonn

  To ensure that the authentication tokens are not left lying around the
  items, PPAAMM__AAUUTTHHTTOOKK and PPAAMM__OOLLDDAAUUTTHHTTOOKK, are reset to NULL when process
  control passes back to the application. This is an action of
  ppaamm__ggeett__uusseerr and the last action of functions ppaamm__aauutthheennttiiccaattee(()) and
  ppaamm__cchhaauutthhttookk(()).  The module developer _m_u_s_t ensure that before calling
  the application supplied conversation function both of the
  authentication tokens are reset to NULL (via two calls to
  ppaamm__sseett__iitteemm(())).

  55..  AAnn eexxaammppllee mmoodduullee ffiillee

  _p_e_r_h_a_p_s _t_h_i_s _s_h_o_u_l_d _p_o_i_n_t _t_o _a _p_l_a_c_e _i_n _t_h_e _f_i_l_e _s_t_r_u_c_t_u_r_e

  66..  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
        Usual repository for LLiinnuuxx--PPAAMM authentication modules.

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

  +o  The LLiinnuuxx--PPAAMM system administrators' guide; pam.html.

  +o  The LLiinnuuxx--PPAAMM application writers' guide; pam_appl.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.

  88..  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! :)

  +o  Perhaps we should keep a registry of data-names as used by
     ppaamm__[[ggss]]eett__ddaattaa(()) so there are no unintentional problems due to
     conflicts?

  +o  ppaamm__[[ggss]]eett__ddaattaa PPAAMM__AAUUTTHHTTOOKK and PPAAMM__OOLLDDAAUUTTHHTTOOKK are only supposed to
     be available to the modules. Does anyone know how to enforce this?
     Marc has made a comment in ppaamm__sseett__iitteemm(()).

  +o  ppaamm__ssttrreerrrroorr(()) should be internationalized....

  +o  ppaamm__ssmm__sseettccrreedd should a pam-module be responsible for checking if a
     user has already been authenticated before allowing a change of
     his/her credentials? Or this a job for the application?

  99..  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.

  1100..  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.

