pam_authenticate(3)

NAME
     pam_authenticate - perform authentication within the PAM framework


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

     #include <security/pam_appl.h>

     int pam_authenticate(pam_handle_t *pamh, int flags);

DESCRIPTION
     pam_authenticate() is called to authenticate the current user.  The user is
     usually  required  to  enter a password or similar authentication token de-
     pending upon the authentication service configured within the system.   The
     user  in question should have been specified by a prior call to pam_start()
     or pam_set_item().  The following flags may be set in the flags field:

            PAM_SILENT                         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

NOTES
     In the case of authentication failures due  to  an  incorrect  username  or
     password,  it is the responsibility of the application to retry pam_authen-
     ticate() and to maintain the retry count.  An authentication service module
     may implement an internal retry count and return an error PAM_MAXRETRIES if
     the module does not want the application to retry.

     If the PAM framework can not load the authentication module, then  it  will
     return  PAM_ABORT.   This indicates a serious failure and that the applica-
     tion should not attempt to retry the authentication.

     For security reasons, the location of  authentication  failures  is  hidden
     from  the user.  Thus, if several authentication services are stacked and a
     single service fails, pam_authenticate() requires that the user  re-authen-
     ticate to all the services.

     A  null  authentication token in the authentication database will result in
     successful authentication unless PAM_DISALLOW_NULL_AUTHTOK  was  specified.
     In such cases, there will not be any prompting for the user to enter an au-
     thentication token.

RETURN VALUES
     Upon  successful  completion,  PAM_SUCCESS is returned.  In addition to the
     error return values described in pam(3), the following values  may  be  re-
     turned:

            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 the underlying au-
                                         thentication module

            PAM_MAXRETRIES               An  authentication  service  has  main-
                                         tained  a  retry  count  which has been
                                         reached. No further retries  should  be
                                         attempted.

SEE ALSO
     pam(3), pam_start(3), pam_open_session(3), pam_setcred(3)