contrib/openpam/doc/man/pam.man

   1 .\"
   2 .\" $Id: pam.man 320 2006-02-16 20:33:19Z des $
   3 .\"
   4 .Sh DESCRIPTION
   5 The Pluggable Authentication Modules (PAM) library abstracts a number
   6 of common authentication-related operations and provides a framework
   7 for dynamically loaded modules that implement these operations in
   8 various ways.
   9 .Ss Terminology
  10 In PAM parlance, the application that uses PAM to authenticate a user
  11 is the server, and is identified for configuration purposes by a
  12 service name, which is often (but not necessarily) the program name.
  13 .Pp
  14 The user requesting authentication is called the applicant, while the
  15 user (usually, root) charged with verifying his identity and granting
  16 him the requested credentials is called the arbitrator.
  17 .Pp
  18 The sequence of operations the server goes through to authenticate a
  19 user and perform whatever task he requested is a PAM transaction; the
  20 context within which the server performs the requested task is called
  21 a session.
  22 .Pp
  23 The functionality embodied by PAM is divided into six primitives
  24 grouped into four facilities: authentication, account management,
  25 session management and password management.
  26 .Ss Conversation
  27 The PAM library expects the application to provide a conversation
  28 callback which it can use to communicate with the user.
  29 Some modules may use specialized conversation functions to communicate
  30 with special hardware such as cryptographic dongles or biometric
  31 devices.
  32 See
  33 .Xr pam_conv 3
  34 for details.
  35 .Ss Initialization and Cleanup
  36 The
  37 .Fn pam_start
  38 function initializes the PAM library and returns a handle which must
  39 be provided in all subsequent function calls.
  40 The transaction state is contained entirely within the structure
  41 identified by this handle, so it is possible to conduct multiple
  42 transactions in parallel.
  43 .Pp
  44 The
  45 .Fn pam_end
  46 function releases all resources associated with the specified context,
  47 and can be called at any time to terminate a PAM transaction.
  48 .Ss Storage
  49 The
  50 .Fn pam_set_item
  51 and
  52 .Fn pam_get_item
  53 functions set and retrieve a number of predefined items, including the
  54 service name, the names of the requesting and target users, the
  55 conversation function, and prompts.
  56 .Pp
  57 The
  58 .Fn pam_set_data
  59 and
  60 .Fn pam_get_data
  61 functions manage named chunks of free-form data, generally used by
  62 modules to store state from one invocation to another.
  63 .Ss Authentication
  64 There are two authentication primitives:
  65 .Fn pam_authenticate
  66 and
  67 .Fn pam_setcred .
  68 The former authenticates the user, while the latter manages his
  69 credentials.
  70 .Ss Account Management
  71 The
  72 .Fn pam_acct_mgmt
  73 function enforces policies such as password expiry, account expiry,
  74 time-of-day restrictions, and so forth.
  75 .Ss Session Management
  76 The
  77 .Fn pam_open_session
  78 and
  79 .Fn pam_close_session
  80 functions handle session setup and teardown.
  81 .Ss Password Management
  82 The
  83 .Fn pam_chauthtok
  84 function allows the server to change the user's password, either at
  85 the user's request or because the password has expired.
  86 .Ss Miscellaneous
  87 The
  88 .Fn pam_putenv ,
  89 .Fn pam_getenv
  90 and
  91 .Fn pam_getenvlist
  92 functions manage a private environment list in which modules can set
  93 environment variables they want the server to export during the
  94 session.
  95 .Pp
  96 The
  97 .Fn pam_strerror
  98 function returns a pointer to a string describing the specified PAM
  99 error code.