3.2. Authentication management

3.2.1. Service function for user authentication

#include <security/pam_modules.h> 
   int pam_sm_authenticate( 
   pamh,  
   flags,  
   argc,  
   argv); 
 pam_handle_t *pamh; 
 int flags; 
 int argc; 
 const char **argv; 

3.2.1.1. DESCRIPTION

The pam_sm_authenticate function is the service module's implementation of the pam_authenticate(3) interface.

This function performs the task of authenticating the user.

Valid flags, which may be logically OR'd with PAM_SILENT , are:

  • PAM_SILENT

    • Do not emit any messages.
  • PAM_DISALLOW_NULL_AUTHTOK

    • Return PAM_AUTH_ERR if the database of authentication tokens for this authentication mechanism has a NULL entry for the user. Without this flag, such a NULL token will lead to a success without the user being prompted.

3.2.1.2. RETURN VALUES

  • PAM_AUTH_ERR

    • Authentication failure.
  • PAM_CRED_INSUFFICIENT

    • For some reason the application does not have sufficient credentials to authenticate the user.
  • PAM_AUTHINFO_UNAVAIL

    • The modules were not able to access the authentication information. This might be due to a network or hardware failure etc.
  • PAM_SUCCESS

    • The authentication token was successfully updated.
  • PAM_USER_UNKNOWN

    • The supplied username is not known to the authentication service.
  • PAM_MAXTRIES

    • One or more of the authentication modules has reached its limit of tries authenticating the user. Do not try again.

3.2.2. Service function to alter credentials

#include <security/pam_modules.h> 
   int pam_sm_setcred( 
   pamh,  
   flags,  
   argc,  
   argv); 
 pam_handle_t *pamh; 
 int flags; 
 int argc; 
 const char **argv; 

3.2.2.1. DESCRIPTION

The pam_sm_setcred function is the service module's implementation of the pam_setcred(3) interface.

This function performs the task of altering the credentials of the user with respect to the corresponding authorization scheme. Generally, an authentication module may have access to more information about a user than their authentication token. This function is used to make such information available to the application. It should only be called after the user has been authenticated but before a session has been established.

Valid flags, which may be logically OR'd with PAM_SILENT , are:

  • PAM_SILENT

    • Do not emit any messages.
  • PAM_ESTABLISH_CRED

    • Initialize the credentials for the user.
  • PAM_DELETE_CRED

    • Delete the credentials associated with the authentication service.
  • PAM_REINITIALIZE_CRED

    • Reinitialize the user credentials.
  • PAM_REFRESH_CRED

    • Extend the lifetime of the user credentials.

The way the auth stack is navigated in order to evaluate the pam_setcred () function call, independent of the pam_sm_setcred () return codes, is exactly the same way that it was navigated when evaluating the pam_authenticate () library call. Typically, if a stack entry was ignored in evaluating pam_authenticate (), it will be ignored when libpam evaluates the pam_setcred () function call. Otherwise, the return codes from each module specific pam_sm_setcred () call are treated as required .

3.2.2.2. RETURN VALUES

  • PAM_CRED_UNAVAIL

    • This module cannot retrieve the user's credentials.
  • PAM_CRED_EXPIRED

    • The user's credentials have expired.
  • PAM_CRED_ERR

    • This module was unable to set the credentials of the user.
  • PAM_SUCCESS

    • The user credential was successfully set.
  • PAM_USER_UNKNOWN

    • The user is not known to this authentication module.

These, non- PAM_SUCCESS , return values will typically lead to the credential stack failing . The first such error will dominate in the return value of pam_setcred ().