PAM Library Functions                      pamauthenticate(3PAM)



NAME
     pamauthenticate - perform  authentication  within  the  PAM
     framework

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


     int pamauthenticate(pamhandlet *pamh, int flags);


DESCRIPTION
     The pamauthenticate() 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 pamstart() or pamsetitem().


     The following flags may be set in the flags field:

     PAMSILENT                   Authentication  service  should
                                  not generate any messages.


     PAMDISALOWNULAUTHTOK    The   authentication    service
                                  should  return  PAMAUTHER if
                                  the user has a null authentica-
                                  tion token.


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

     PAMAUTHER             Authentication failure.


     PAMCREDINSUFICIENT    Cannot access  authentication  data
                              due to insufficient credentials.


     PAMAUTHINFOUNAVAIL     Underlying  authentication  service
                              cannot    retrieve   authentication
                              information.


     PAMUSERUNKNOWN         User not known  to  the  underlying
                              authentication module.



SunOS 5.11          Last change: 27 Jan 2005                    1






PAM Library Functions                      pamauthenticate(3PAM)



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


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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability           Stable                     
    
     MT-Level                     MT-Safe with exceptions     
    


SEE ALSO
     pam(3PAM),    pamopensession(3PAM),    pamsetitem(3PAM),
     pamsetcred(3PAM),   pamstart(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 pamauthenticate() and to maintain the retry
     count.  An  authentication  service  module may implement an
     internal retry count and return an error PAMAXTRIES if the
     module does not want the application to retry.


     If the  PAM framework cannot load the authentication module,
     then  it  will  return   PAMABORT. 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,
     pamauthenticate()  requires  that  the user re-authenticate
     each of the services.


     A null authentication token in the  authentication  database
     will    result    in    successful   authentication   unless
     PAMDISALOWNULAUTHTOK  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                      pamauthenticate(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