PAM Library Functions                   pamsmauthenticate(3PAM)



NAME
     pamsmauthenticate - service  provider  implementation  for
     pamauthenticate

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


     int pamsmauthenticate(pamhandlet *pamh, int flags,
          int argc, const char **argv);


DESCRIPTION
     In response to a call to  pamauthenticate(3PAM),  the   PAM
     framework   calls  pamsmauthenticate()  from  the  modules
     listed in the pam.conf(4) file. The authentication  provider
     supplies the back-end functionality for this interface func-
     tion.


     The pamsmauthenticate() function is called to  verify  the
     identity  of  the current user. The user is usually required
     to enter a password or similar authentication token  depend-
     ing  upon  the  authentication  scheme configured within the
     system. The user in question is specified by a prior call to
     pamstart(),  and is referenced by the authentication handle
     pamh.


     If the user is unknown to the  authentication  service,  the
     service module should mask this error and continue to prompt
     the user for a password. It should then  return  the  error,
     PAMUSERUNKNOWN.


     The    following    flag    may    be    passed    in     to
     pamsmauthenticate():

     PAMSILENT                   The   authentication    service
                                  should  not  generate  any mes-
                                  sages.


     PAMDISALOWNULAUTHTOK    The   authentication    service
                                  should return


     PAMAUTHER                 The user has a null authentica-
                                  tion token.




SunOS 5.11          Last change: 27 Jan 2005                    1






PAM Library Functions                   pamsmauthenticate(3PAM)



     The argc argument represents the number  of  module  options
     passed  in  from  the  configuration  file pam.conf(4). argv
     specifies the module options, which are interpreted and pro-
     cessed  by  the  authentication service. Please refer to the
     specific module man pages for the various available options.
     If  any  unknown  option is passed in, the module should log
     the error and ignore the option.


     Before   returning,   pamsmauthenticate()   should    call
     pamgetitem()  and retrieve PAMAUTHTOK. If it has not been
     set before and  the  value  is  NUL,  pamsmauthenticate()
     should  set  it  to  the  password entered by the user using
     pamsetitem().


     An authentication module may save the authentication  status
     (success  or reason for failure) as state in the authentica-
     tion handle using pamsetdata(3PAM).  This  information  is
     intended for use by pamsetcred().

RETURN VALUES
     Upon successful completion,  PAMSUCES must  be  returned.
     In addition, the following values may be returned:

     PAMAXTRIES             Maximum  number  of  authentication
                              attempts exceeded.


     PAMAUTHER             Authentication failure.


     PAMCREDINSUFICIENT    Cannot access  authentication  data
                              due to insufficient credentials.


     PAMAUTHINFOUNAVAIL     Underlying  authentication  service
                              can   not  retrieve  authentication
                              information.


     PAMUSERUNKNOWN         User  not   known   to   underlying
                              authentication module.


     PAMIGNORE               Ignore  underlying   authentication
                              module  regardless  of  whether the
                              control flag is  required,optional,
                              or sufficient1.






SunOS 5.11          Last change: 27 Jan 2005                    2






PAM Library Functions                   pamsmauthenticate(3PAM)



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),    pamauthenticate(3PAM),    pamgetitem(3PAM),
     pamsetdata(3PAM),  pamsetitem(3PAM),  pamsetcred(3PAM),
     pamstart(3PAM), libpam(3LIB), pam.conf(4), attributes(5)

NOTES
     Modules should not retry the authentication in the event  of
     a  failure.  Applications  handle authentication retries and
     maintain the retry count. To limit the  number  of  retries,
     the module can return a PAMAXTRIES error.


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


     If the PAMREPOSITORY itemtype is set and a service  module
     does  not  recognize  the  type, the service module does not
     process any information,  and  returns  PAMIGNORE.  If  the
     PAMREPOSITORY  itemtype  is not set, a service module per-
     forms its default action.


















SunOS 5.11          Last change: 27 Jan 2005                    3