3.2. Authentication management

To be correctly initialized, PAM_SM_AUTH must be #define 'd prior to including <security/pam_modules.h> . This will ensure that the prototypes for static modules are properly declared.

3.2.1. Service function for user authentication

#define PAM_SM_AUTH
#include <security/pam_modules.h>
   PAM_EXTERN 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

#define PAM_SM_AUTH
#include <security/pam_modules.h>
   PAM_EXTERN 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 ().

Updated at: 5 months ago
3.1.3. Arguments supplied to the moduleTable of content3.3. Account management