9.2 About PAM Operation for an Application

An application typically performs the following steps during the invocation of a typical PAM session.

  1. Call pam_start() to initialize the PAM library, specify its service name and the target account, and register a suitable conversation function.

    #include <security/pam_appl.h>
    
    int pam_start(const char *service, const char *user, const struct pam_conv *pam_conv,
                  pam_handle_t **pamh); 

    pam_start() returns a PAM session handle pamh for use with subsequent function calls.

  2. Obtain information relating to the transaction (such as the applicant's user name and the name of the host on which the client runs) and use pam_set_item() to submits it to PAM.

    int pam_set_item(pam_handle_t *pamh, int item_type, const void *item);
  3. Call pam_authenticate() to authenticate the applicant.

    int pam_authenticate(pam_handle_t *pamh, int flags);
  4. Once the user has been authenticated, call pam_acct_mgmt() to establish whether the account is valid and the user is permitted to log in at this time. Optionally, modules of type account-management can be used to restrict users from logging in at certain times of the day or week or for enforcing password expiration. In this case, users are prevented from gaining access to the system until they have successfully updated their password with the pam_chauthtok() function.

    int pam_acct_mgmt(pam_handle_t *pamh, int flags);

    If the password is correct but has expired, pam_acct_mgmt() returns PAM_NEW_AUTHTOK_REQD instead of PAM_SUCCESS.

    If the function returns PAM_NEW_AUTHTOK_REQD, call pam_chauthtok() to force the client to change the authentication token for the requested account.

    int pam_chauthtok(pam_handle_t *pamh, const int flags);
  5. Call pam_setcred() to establish the identity of the user, which can include credentials such as access tickets and supplementary group memberships.

    int pam_setcred(pam_handle_t *pamh, int flags);
  6. When the credentials have been established, call pam_open_session() to open and configure the session, which typically includes performing tasks such as making system resources available (for example, mounting a user's home directory) and establishing an audit trail.

    int pam_open_session(pam_handle_t *pamh, int flags);
  7. To close the session, call pam_close_session().

    int pam_close_session(pam_handle_t *pamh, int flags);
  8. Call pam_end() to notify the PAM library that the application has finished processing a transaction and that it can release whatever resources it has allocated in the course of the transaction.

    int pam_end(pam_handle_t *pamh, int status);