  The LLiinnuuxx--PPAAMM Application Developers' 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 an application developer needs to know
  about the LLiinnuuxx--PPAAMM library. It describes how an application might use
  the LLiinnuuxx--PPAAMM library to authenticate users. It also contains some
  comments on PAM related security issues for the application developer.

  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_appl.h>

       cc -o application .... -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) 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
  pam.html.

  It is the purpose of the LLiinnuuxx--PPAAMM project to liberate the development
  of privilege granting software from the development of secure and
  appropriate authentication schemes.  This is accomplished by providing
  a documented library of functions that an application may use for all
  forms of user authentication management. This library dynamically
  loads locally configured authentication modules that actually perform
  the task of user authentication.

  From the perspective of an application developer the information
  contained in the local configuration of the PAM library should not be
  important. Indeed it is intended that an application treat the
  functions documented in this file as a ``black box'' that will deal
  with all aspects of user authentication. ``All aspects'' includes user
  verification and also the resetting of passwords etc. .

  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 LLiinnuuxx--PPAAMM

  Firstly, the relevant include file for the LLiinnuuxx--PPAAMM library is
  <<sseeccuurriittyy//ppaamm__aappppll..hh>>. It contains the definitions for a number of
  functions. Before listing these functions, we collect some guiding
  remarks for programmers.

  22..11..  PPrrooggrraammmmiinngg nnootteess

  In general writers of authorization-granting applications should
  assume that each module is likely to call any or _a_l_l `libc' functions.
  For `libc' functions that return pointers to static/dynamically
  allocated structures (ie. the library allocates the memory and the
  user is not expected to `ffrreeee(())' it) any module call to this function
  is likely to corrupt a pointer previously obtained by the application.
  The application programmer should either re-call such a libc function
  after any call to the LLiinnuuxx--PPAAMM library, or copy the structure
  contents to some safe area of memory before passing control to the
  LLiinnuuxx--PPAAMM library.

  22..22..  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 aapppplliiccaattiioonn

  Here we document those functions in the LLiinnuuxx--PPAAMM library that may be
  called from an application.

  +o  eexxtteerrnn iinntt ppaamm__ssttaarrtt((cchhaarr **sseerrvviiccee__nnaammee,, cchhaarr **uusseerr,, ssttrruucctt
     ppaamm__ccoonnvv **ppaamm__ccoonnvveerrssaattiioonn,, ppaamm__hhaannddllee__tt ****ppaammhh));;

     This is the first of the LLiinnuuxx--PPAAMM functions that must be called by
     an application. It initializes the interface and reads the system
     configuration file, //eettcc//ppaamm..ccoonnff (see pam.html). Following a
     successful return (PPAAMM__SSUUCCCCEESSSS) the contents of **ppaammhh is a handle
     that provides continuity for successive calls to the LLiinnuuxx--PPAAMM
     library. The arguments expected by ppaamm__ssttaarrtt are as follows: the
     sseerrvviiccee__nnaammee of the program, the uusseerrname of the individual to be
     authenticated, a pointer to an application-supplied ppaamm__ccoonnvv
     structure and a pointer to a ppaamm__hhaannddllee__tt _p_o_i_n_t_e_r.

     The ppaamm__ccoonnvv structure is discussed more fully below in the section
     covering ``What is expected of an application''. The ppaamm__hhaannddllee__tt
     is a _b_l_i_n_d structure and the application should not attempt to
     probe it directly for information. Instead the LLiinnuuxx--PPAAMM library
     provides the functions ppaamm__sseett__iitteemm and ppaamm__ggeett__iitteemm. These
     functions are documented below.

  +o  eexxtteerrnn iinntt ppaamm__eenndd((ppaamm__hhaannddllee__tt **ppaammhh,, iinntt ppaamm__ssttaattuuss));;

     This function is the last function an application should call in
     the LLiinnuuxx--PPAAMM library. Upon return the handle ppaammhh is no longer
     valid. Under normal conditions the argument ppaamm__ssttaattuuss has the
     value PAM_SUCCESS, but its purpose is to be passed as an argument
     to the module specific function cclleeaannuupp(()) (see pam_modules.html.
     XXX -- see notes

  +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 following
     iitteemm__ttyyppees:

     PPAAMM__SSEERRVVIICCEE
        The service name

     PPAAMM__UUSSEERR
        The user name

     PPAAMM__TTTTYY
        The terminal name

     PPAAMM__RRHHOOSSTT
        The remote host name

     PPAAMM__CCOONNVV
        The pam_conv structure (see below)

     PPAAMM__RRUUSSEERR
        The remote user name

     PPAAMM__UUSSEERR__PPRROOMMPPTT
        The string used when prompting for a user's name.

     For all iitteemm__ttyyppees, but PPAAMM__CCOONNVV, iitteemm is a pointer to a ''\\00''
     terminated character string. In the case of PPAAMM__CCOONNVV, iitteemm points
     to an initialized ppaamm__ccoonnvv structure (see below).

  +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 indicated
     iitteemm__ttyyppee.  Upon successful return, **iitteemm contains a pointer to the
     value of the corresponding item. Note, this is a pointer to the
     _a_c_t_u_a_l data and should _n_o_t be ffrreeee(())'ed or over-written!  If an
     attempt is made to get an undefined item, PPAAMM__BBAADD__IITTEEMM is returned.

  +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

  +o  eexxtteerrnn iinntt ppaam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));;

     This function serves as an interface to the authentication
     mechanisms of the loaded modules. Valid flags, which may be
     logically OR'd, are

     PPAAMM__SSIILLEENNTT
        Instruct the authentication modules to not generate any
        messages, and

     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
        Instruct the authentication modules to return PPAAMM__AAUUTTHHTTOOKKEENN__RREEQQDD
        if the _i_t_e_m, PPAAMM__AAUUTTHHTTOOKK, is set to NNUULLLL.

     If one or more of the authentication modules fails to load, for
     whatever reason, this function will return PPAAMM__AABBOORRTT.

  +o  eexxtteerrnn iinntt ppaam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));;

     This function is used to set the module-specific credentials of the
     user. It is usually called after the user has been authenticated.
     Currently, this function simply calls the ppaamm__ssmm__sseettccrreedd functions
     of each of the loaded modules.  Valid ffllaaggss, which may be logically
     OR'd, are:

     PPAAMM__CCRREEDD__EESSTTAABBLLIISSHH
        Set the credentials for the authentication service,

     PPAAMM__CCRREEDD__DDEELLEETTEE
        Delete the credentials associated with the authentication
        service,

     PPAAMM__CCRREEDD__RREEIINNIITTIIAALLIIZZEE
        Reinitialize the user credentials, and

     PPAAMM__CCRREEDD__RREEFFRREESSHH
        Extend the lifetime of the user credentials.

  +o  eexxtteerrnn iinntt ppaam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));;

     This function is typically called after the user has been
     authenticated. It establishes whether the user's account is
     healthy. That is to say, whether the user's account is still active
     and whether the user is permitted to gain access to the system at
     this time. Valid flags, which may be logically OR'd, are the same
     as those applicable to the ffllaaggss argument of ppaamm__aauutthheennttiiccaattee.

     Currently, this function simply calls the corresponding functions
     of each of the loaded modules, as instructed by the configuration
     file, //eettcc//ppaamm..ccoonnff.

  +o  eexxtteerrnn iinntt ppaam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));;

     This function is used to indicate that an authenticated session has
     begun. It is used to inform the module that the user is currently
     in a session. It should be possible for the LLiinnuuxx--PPAAMM library to
     open a session and close the same session (see below) from
     different applications.

     Currently, this function simply calls each of the corresponding
     functions of the loaded modules.  XXX - see notes

     If any of the _r_e_q_u_i_r_e_d loaded modules are unable to open a session
     for the user, this function will return PPAAMM__SSEESSSSIIOONN__EERRRR.

  +o  eexxtteerrnn iinntt ppaam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));;

     This function is used to indicate that an authenticated session has
     ended. It is used to inform the module that the user is exiting a
     session. It should be possible for the LLiinnuuxx--PPAAMM library to open a
     session and close the same session from different applications.

     Currently, this function simply calls each of the corresponding
     functions of the loaded modules.  XXX - see notes

     If any of the _r_e_q_u_i_r_e_d loaded modules are unable to close a session
     for the user, this function will return PPAAMM__SSEESSSSIIOONN__EERRRR.

  +o  eexxtteerrnn iinntt ppaam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,, ccoonnsstt iinntt ffllaaggss));;

     This function is used to change the authentication token for a
     given user (as indicated by the state associated with the handle,
     ppaammhh). Valid flags, which may be logically OR'd, are those
     associated with a call to ppaamm__aauutthheennttiiccaattee above.

  22..33..  WWhhaatt iiss eexxppeecctteedd ooff aann aapppplliiccaattiioonn

  An application must provide a ``conversation function''. It is used
  for direct communication between a loaded module and the application
  and will typically provide a means for the module to prompt the user
  for a password etc. . The structure ppaamm__ccoonnvv is defined in
  <security/pam_appl.h> to be,

       struct pam_conv {
           int (*conv)(int num_msg,
               const struct pam_message **msg,
               struct pam_response **resp,
               void *appdata_ptr);
           void *appdata_ptr;
       };

  It is initialized by the application before it is passed to the
  library. The contents of this structure are attached to the **ppaammhh
  handle.  The point of this argument is to provide a mechanism for any
  loaded module to interact directly with the application program. This
  is why it is called a _c_o_n_v_e_r_s_a_t_i_o_n structure.

  When a module calls the referenced ccoonnvv(()) function, the argument
  **aappppddaattaa__ppttrr is set to the second element of this structure.

  The other arguments of a call to ccoonnvv(()) concern the information
  exchanged by module and application. That is to say, nnuumm__mmssgg holds the
  length of the array of pointers, mmssgg. After a successful return, the
  pointer **rreesspp points to a ppaamm__rreessppoonnssee structure, holding the
  application supplied text.

  The message (from the module to the application) passing structure is
  defined in <<sseeccuurriittyy//ppaamm__aappppll..hh>> as:

       struct pam_message {
           int msg_style;
           char *msg;
       };

  Valid choices for mmssgg__ssttyyllee are:

     PPAAMM__PPRROOMMPPTT__EECCHHOO__OOFFFF
        Obtain a string without echoing any text

     PPAAMM__PPRROOMMPPTT__EECCHHOO__OONN
        Obtain a string whilst echoing text

     PPAAMM__EERRRROORR__MMSSGG
        Display an error

     PPAAMM__TTEEXXTT__IINNFFOO
        Display some text.

  The response (from the application to the module) passing structure is
  defined in <<sseeccuurriittyy//ppaamm__aappppll..hh>> as:

       struct pam_response {
           char *resp;
           int resp_retcode;
       };

  Currently, there are no definitions for rreesspp__rreettccooddee values. The
  normal response is 00.  XXX - see notes

  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 applications
  programmers...

  Clearly it is a good idea to always check the return value of a call
  to any function of LLiinnuuxx--PPAAMM.

  Care should be taken to ensure that the ccoonnvv(()) function is robust.
  XXX - see notes

  44..  AAnn eexxaammppllee aapppplliiccaattiioonn

  _I_t _w_o_u_l_d _b_e _n_i_c_e _t_o _g_i_v_e _a _s_i_m_p_l_e _t_e_m_p_l_a_t_e _f_o_r _a _P_A_M_-_a_w_a_r_e _a_p_p_l_i_c_a_t_i_o_n
  _h_e_r_e_. _I _g_u_e_s_s _i_t _n_e_e_d _n_o_t _g_r_a_n_t _a_n_y _p_r_i_v_i_l_e_g_e_s_, _b_u_t _r_a_t_h_e_r _j_u_s_t _p_r_i_n_t
  _`_`_a_u_t_h_e_n_t_i_c_a_t_i_o_n _s_u_c_c_e_e_d_e_d_/_f_a_i_l_e_d_'_'_. _I_t _w_o_u_l_d _a_l_s_o _b_e _r_a_t_h_e_r _u_s_e_f_u_l
  _f_o_r _d_e_v_e_l_o_p_i_n_g _m_o_d_u_l_e_s_.

  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 system administrators' guide; pam.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! :)

  +o  the ppaamm__ssttaattuuss argument of ppaamm__eenndd(()) is passed to cclleeaannuupp(())? This
     seems dangerously close to making applications module specific...?
     Perhaps someone can clarify this for me? Is there going to be a
     recognized list of valid pam_status arguments? I guess it should be
     in <security/pam_appl.h>?

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

  +o  need a simple example application.

  +o  ppaamm__ooppeenn//cclloossee__sseessssiioonn, these functions will get a better write up
     once I appreciate them better!

  +o  ppaamm__ccoonnvv.. This seems to be a good way for the module to set
     application environment variables etc. from the module . Might I
     suggest that (see rfc86.0 pp26-27) we have a special action for the
     conv function when the nnuumm__mmssgg argument is _n_e_g_a_t_i_v_e. For example,
     if nnuumm__mmeessgg====PPAAMM__EEXXPPOORRTT__EENNVV(( == --11 )), then the mmssgg pointer points at
     an array of two ppaamm__mmeessssaaggee structures holding the name of the
     environment variable and its value. While we are at it the **rreesspp
     pointer can be directed at a pam_response holding the _p_r_e_v_i_o_u_s
     value of this variable (or NNUULLLL). Thoughts?

  +o  Note, the rreesspp__rreettccooddee of struct ppaamm__mmeessssaaggee, has no purpose at the
     moment. Ideas/suggestions welcome!

  +o  perhaps this comment should be in the pam_modules manual (too)? On
     return from a call to ccoonnvv(()) the _r_e_s_p_o_n_s_e should be copied to some
     allocated memory. This will ensure that no static variables etc. in
     the application cause problems when used repeatedly!

  +o  more work needs to be done, documenting valid responses of the
     various function calls. The security issues bit is currently rather
     pathetic.

  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.

