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.

• PAM_EXTERN int pam_sm_authenticate(pam_handle_t *pamh, int flags, int argc, const char **argv);

  This function performs the task of authenticating the user.

  The flags argument can be a logically OR'd with PAM_SILENT and optionally take the following value:

  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.

  Besides PAM_SUCCESS return values that can be sent by this function are one of the following:

  PAM_AUTH_ERR

  The user was not authenticated

  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_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.

• PAM_EXTERN int pam_sm_setcred(pam_handle_t *pamh, int flags, int argc, const char **argv);

  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 append such information to the application. It should only be called after the user has been authenticated.

  Permitted flags, one of which, may be logically OR'd with PAM_SILENT are,

  PAM_CRED_ESTABLISH

  Set the credentials for the authentication service,

  PAM_CRED_DELETE

  Delete the credentials associated with the authentication service,

  PAM_CRED_REINITIALIZE

  Reinitialize the user credentials, and

  PAM_CRED_REFRESH

  Extend the lifetime of the user credentials.

  Besides PAM_SUCCESS, the module may return one of the following errors:

  PAM_CRED_UNAVAIL

  This module cannot retrieve the user's credentials.

  PAM_CRED_EXPIRED

  The user's credentials have expired.

  PAM_USER_UNKNOWN

  The user is not known to this authentication module.

  PAM_CRED_ERR

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