pam_sm_authenticate(3)

NAME
     pam_sm_authenticate - Service provider implementation for pam_authenticate

SYNOPSIS
     cc [ flag ... ] file ...  -lpam [ library ... ]

     #include <security/pam_appl.h>
     #include <security/pam_modules.h>

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

DESCRIPTION
     In  response  to  a  call  to  pam_authenticate(3), the PAM framework calls
     pam_sm_authenticate() from the modules listed in the pam.conf(4) file.  The
     authentication provider supplies the back-end functionality for this inter-
     face function.

     The function, pam_sm_authenticate(), is called to verify  the  identity  of
     the current user.  The user is usually required to enter a password or sim-
     ilar  authentication token depending upon the authentication scheme config-
     ured within the system.  The user in question is specified by a prior  call
     to pam_start(), and is referenced by the authentication handle, pamh.

     The following flag may be passed in to pam_sm_authenticate():

            PAM_SILENT                         The authentication service should
                                               not generate any messages

            PAM_DISALLOW_NULL_AUTHTOK          The authentication service should
                                               return PAM_AUTH_ERROR if the user
                                               has a null authentication token

     The  argc  argument represents the number of service options passed in from
     the configuration file pam.conf(4).  argv specifies  the  service  options,
     which  are interpreted and processed by the authentication service.  Please
     refer to the specific module man pages for the various  available  options.
     If any unknown option is passed in, the module should log the error and ig-
     nore the option.


NOTES
     Modules should not retry the authentication in the event of a failure.  Ap-
     plications  should  handle authentication retries and maintaining the retry
     count.  However modules may save  the  authentication  status  (success  or
     failure) using the pam_set_data(3) function.


RETURN VALUES
     Upon successful completion, PAM_SUCCESS must be returned.  In addition, the
     following values may be returned:

            PAM_MAXTRIES                 Maximum  number  of  authentication at-
                                         tempts exceeded

            PAM_AUTH_ERR                 Authentication failure

            PAM_CRED_INSUFFICIENT        Can not access authentication data  due
                                         to insufficient credentials

            PAM_AUTHINFO_UNAVAIL         Underlying  authentication  service can
                                         not retrieve authentication information

            PAM_USER_UNKNOWN             User not known to underlying  authenti-
                                         cation module

            PAM_IGNORE                   Ignore underlying authentication module
                                         regardless  of whether the control flag
                                         is required, optional or sufficient

SEE ALSO
     pam(3), pam_authenticate(3), pam.conf(4)