Pluggable Authentication Module Library (libpam, -lpam)

     pam_acct_mgmt, pam_authenticate, pam_chauthtok, pam_close_session, pam_end, pam_get_data, pam_get_item, pam_get_user,
     pam_getenv, pam_getenvlist, pam_open_session, pam_putenv, pam_set_data, pam_set_item, pam_setcred, pam_start,
     pam_strerror 
Linux-PAM system administrators' guide
conf

LIBRARY

Abstracts a number of common authentication-related operations and provides a framework for dynamically loaded modules .

Terminology

The application that uses PAM to authenticate a user is the server, and is identified for configuration purposes by a service name, which is often (but not necessarily) the program name.

The user requesting authentication is called the applicant,
while the user (usually, root) charged with verifying his identity and granting him the requested credentials is called the arbitrator.

The sequence of operations the server goes through to authenticate a user and perform whatever task he requested is a PAM transaction; the context within which the server performs the requested task is called a session

. The functionality embodied by PAM is divided into primitives; grouped into facilities:

  1. authentication,
  2. account management,
  3. session management and
  4. password management.
  1. Conversation
    application will provide a conversation callback to communicate with the user. Some modules may use specialized conversation functions to communicate with special hardware such as cryptographic dongles or biometric devices. See pam_conv
  2. Initialization and Cleanup
    start initializes the PAM library and returns a handle which must be provided in all subsequent function calls. The transaction state is contained entirely within the structure identified by this handle, so it is possible to conduct multiple transactions in parallel.
    end releases all resources associated with the specified context, and can be called at any time to terminate a PAM transaction.
  3. Storage
    set_item and get_item set and retrieve a number of predefined items, including the service name, the names of the requesting and target users, the conversation function, and prompts.

    set_data and get_data manage named chunks of free-form data, generally used by modules to store state from one invocation to another.

  4. Authentication
    authentication primitives:
    authenticate authenticates the user,
    setcred: the latter manages his credentials.
  5. Account Management
    acct_mgmt enforces policies such as password expiry, account expiry, time-of-day restrictions, etc.
  6. Session Management
    open_session and close_session
  7. Password Management
    pam_chauthtok allows the server to change the user's password, at the user's request or because the it has expired.
  8. Miscellaneous
    putenv, getenv and getenvlist manage a private environment list in which modules can set environment variables for the server to export during the session.
     #include <security/pam_appl.h>

     int pam_acct_mgmt(pam_handle_t *pamh, int flags); 
     int pam_open_session(pam_handle_t *pamh, int flags); 
     int pam_authenticate(pam_handle_t *pamh, int flags); 
     int pam_chauthtok(pam_handle_t *pamh, int flags); 
     int pam_get_data(const pam_handle_t *pamh, const char *module_data_name, const void **data); 
     int pam_get_item(const pam_handle_t *pamh, int item_type, const void **item); 
     int pam_get_user(pam_handle_t *pamh, const char **user, const char *prompt); 
const char * pam_getenv(pam_handle_t *pamh, const char *name); 
 char ** pam_getenvlist(pam_handle_t *pamh); 

     int pam_putenv(pam_handle_t *pamh, const char *namevalue); 
     int pam_set_data(pam_handle_t *pamh, const char *module_data_name, void *data, void (*cleanup)(pam_handle_t *pamh, void *data, int pam_end_status)); 
     int pam_set_item(pam_handle_t *pamh, int item_type, const void *item);
int pam_setcred(pam_handle_t *pamh, int flags); 
     int pam_start(const char *service, const char *user, const struct pam_conv *pam_conv, pam_handle_t **pamh); 
     int pam_close_session(pam_handle_t *pamh, int flags); 
     int pam_end(pam_handle_t *pamh, int status); 
     const char * pam_strerror(const pam_handle_t *pamh, int error_number);

RETURN VALUES

Defined in <security/pam_constants.h>:

     [PAM_ABORT]         General failure.  
     [PAM_ACCT_EXPIRED]  
     [PAM_AUTHINFO_UNAVAIL] 
     [PAM_AUTHTOK_DISABLE_AGING] 
     [PAM_AUTHTOK_ERR]  
     [PAM_AUTHTOK_EXPIRED]
     [PAM_AUTHTOK_LOCK_BUSY]
     [PAM_AUTHTOK_RECOVERY_ERR] Failed to recover old authentication token.  
     [PAM_AUTH_ERR]    

     [PAM_CONV_ERR]  
     [PAM_BUF_ERR]    
     [PAM_CRED_ERR]      Failed to set user credentials.  
     [PAM_CRED_EXPIRED] 
     [PAM_CRED_INSUFFICIENT]
     [PAM_CRED_UNAVAIL]  Failed to retrieve user credentials.  
     [PAM_DOMAIN_UNKNOWN] Unknown authentication domain.  
     [PAM_IGNORE]        
     [PAM_MAXTRIES]     
     [PAM_MODULE_UNKNOWN] Unknown module type.  
     [PAM_NEW_AUTHTOK_REQD] 
     [PAM_NO_MODULE_DATA]
     [PAM_OPEN_ERR]      Failed to load module.  
     [PAM_PERM_DENIED]  
     [PAM_SUCCESS]       
     [PAM_SERVICE_ERR]  [PAM_SESSION_ERR] [PAM_SYMBOL_ERR]   [PAM_SYSTEM_ERR]  
     [PAM_TRY_AGAIN]  
     [PAM_USER_UNKNOWN]

SEE ALSO

openpam(3), pam_acct_mgmt(3), pam_authenticate(3), pam_chauthtok(3), pam_close_session(3), pam_conv(3), pam_end(3), pam_get_data(3), pam_getenv(3), pam_getenvlist(3), pam_get_item(3), pam_get_user(3), pam_open_session(3), pam_putenv(3), pam_setcred(3), pam_set_data(3), pam_set_item(3), pam_start(3), pam_strerror(3)

files

STANDARDS

X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules, June 1997.