Manual Pages for UNIX Operating System command usage for man pam_authenticate

PAM Library Functions                      pam_authenticate(3PAM)



NAME
     pam_authenticate - perform  authentication  within  the  PAM
     framework

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

     int pam_authenticate(pam_handle_t *pamh, int flags);


DESCRIPTION
     The pam_authenticate() function is  called  to  authenticate
     the  current  user.  The user is usually required to enter a
     password or similar authentication token depending 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_ERR if
                                  the user has a null authentica-
                                  tion token.


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

     PAM_AUTH_ERR             Authentication failure.


     PAM_CRED_INSUFFICIENT    Cannot access  authentication  data
                              due to insufficient credentials.


     PAM_AUTHINFO_UNAVAIL     Underlying  authentication  service
                              cannot    retrieve   authentication
                              information.


     PAM_USER_UNKNOWN         User not known  to  the  underlying
                              authentication module.




SunOS 5.11          Last change: 27 Jan 2005                    1






PAM Library Functions                      pam_authenticate(3PAM)



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


ATTRIBUTES
     See attributes(5) for description of  the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe with exceptions     |
    |_____________________________|_____________________________|


SEE ALSO
     pam(3PAM),    pam_open_session(3PAM),    pam_set_item(3PAM),
     pam_setcred(3PAM),   pam_start(3PAM),  libpam(3LIB),  attri-
     butes(5)

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


     If the  PAM framework cannot load the authentication module,
     then  it  will  return   PAM_ABORT. This indicates a serious
     failure, and  the application should not  attempt  to  retry
     the authentication.


     For  security  reasons,  the  location   of   authentication
     failures is hidden from the user.   Thus, if several authen-
     tication services are stacked and a  single  service  fails,
     pam_authenticate()  requires  that  the user re-authenticate
     each of 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   be   no  prompt  to  the  user  to  enter  an



SunOS 5.11          Last change: 27 Jan 2005                    2






PAM Library Functions                      pam_authenticate(3PAM)



     authentication token.


     The interfaces in  libpam are MT-Safe only  if  each  thread
     within  the multithreaded application uses its own  PAM han-
     dle.

















































SunOS 5.11          Last change: 27 Jan 2005                    3