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