PAM Library Functions                      pam_authenticate(3PAM)

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
     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  mes-
           sages.

     PAM_DISALLOW_NULL_AUTHTOK
           The    authentication    service     should     return
           PAM_AUTH_ERROR  if  the user has a null authentication
           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.

     PAM_MAXTRIES
           An authentication service has maintained a retry count
           which  has  been reached. No further retries should be

SunOS 5.8           Last change: 13 Oct 1998                    1

PAM Library Functions                      pam_authenticate(3PAM)

           attempted.

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         |  Stable                     |
    |_____________________________|_____________________________|
    | 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),  attributes(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 authentica-
     tion token.

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

SunOS 5.8           Last change: 13 Oct 1998                    2