PAMAUTHENTICATE(3) App. Programmers' Manual PAMAUTHENTICATE(3)

NAME
       pamauthenticate - authenticate a user


SYNOPSIS
       ##iinncclluuddee <>

       iinntt ppaammaauutthheennttiiccaattee((ppaammhhaannddlleett *pamh,, iinntt  flags));;



DESCRIPTION
       ppaammaauutthheennttiiccaattee

       Use  this  function  to  authenticate  an applicant user.  It is linked
       dynamically to the authentication modules by LLiinnuuxx-PPAAMM.  It is the task
       of these module to perform such an authentication.  The specific nature
       of the authentication is not the concern of the application.

       Following successful completion, the nnaammee  of  the  authenticated  user
       will  be  present  in  the  LLiinnuuxx-PPAAMM  item PPAAMMUUSSEERR.  This item may be
       recovered with a call to ppaammggeettiitteemm(3).

       The application developer should note that the modules may request that
       the  user  enter  their  username  via  the conversation mechanism (see
       ppaammssttaarrtt(3)).  Should this be the case, the user-prompt string can  be
       set via the PPAAMMUUSSEERRPPRROOMMPPTT item (see ppaammsseettiitteemm(3)).


RREETTUURRNN VVAALLUUEE
       On  success  PPAAMMSSUUCCCCEESSSS is returned.  All other returns should be con-
       sidered authentication failures and will be delayed by an amount speci-
       fied  with  prior  calls  to ppaammffaaiillddeellaayy(3).  Specific failures that
       demand special attention are the following:

       PPAAMMAABBOORRTT
              the application should exit immediately. Of  course,  ppaammeenndd(3)
              should be called first.


       PPAAMMMMAAXXTTRRIIEESS
              the  application  has  tried  too many times to authenticate the
              user, authentication should not be attempted again.


EERRRROORRSS
       May be translated to text with ppaammssttrreerrrroorr(3).


CCOONNFFOORRMMIINNGG TTOO
       DCE-RFC 86.0, October 1995.


BUGS
       none known.


SEE ALSO
       ppaammssttaarrtt(3), ppaammggeettiitteemm(3) ppaammffaaiillddeellaayy(3) and ppaammssttrreerrrroorr(3).

       Also, see the three LLiinnuuxx-PPAAMM Guides, for SSyysstteemm aaddmmiinniissttrraattoorrss, mmoodduullee
       ddeevveellooppeerrss, and aapppplliiccaattiioonn ddeevveellooppeerrss.



Linux-PAM 0.55                    1996 Dec 9               PAMAUTHENTICATE(3)