PAM Library Functions                             pamstart(3PAM)



NAME
     pamstart, pamend - PAM  authentication  transaction  func-
     tions

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

     int pamstart(const char *service, const char *user,
          const struct pamconv *pamconv, pamhandlet **pamh);


     int pamend(pamhandlet *pamh, int status);


DESCRIPTION
     The pamstart() function is called to initiate an  authenti-
     cation  transaction.  It  takes as arguments the name of the
     current service, service, the name of the user to be authen-
     ticated,  user,  the  address of the conversation structure,
     pamconv, and the address of a variable to be  assigned  the
     authentication  handle  pamh.  Upon  successful  completion,
     pamh refers to a PAM handle for use with subsequent calls to
     the authentication library.


     The  pamconv structure contains the address of the  conver-
     sation function provided by the application.  The underlying
     PAM service module invokes this function to output  informa-
     tion  to  and  retrieve  input  from  the user. The pamconv
     structure has the following entries:

       struct pamconv {
           int   (*conv)();     /* Conversation function */
           void  *appdataptr;  /* Application data */
       };


       int conv(int nummsg, const struct pammessage **msg,
                struct pamresponse **resp, void *appdataptr);



     The conv() function is called by a service module to hold  a
     PAM  conversation  with  the application or user. For window
     applications, the application can create a new pop-up window
     to be used by the interaction.


     The nummsg  parameter is the number of messages  associated
     with the call. The parameter msg is a pointer to an array of
     length nummsg of the pammessage structure.



SunOS 5.11          Last change: 22 Feb 2005                    1






PAM Library Functions                             pamstart(3PAM)



     The pammessage structure is used to pass prompt, error mes-
     sage,  or  any text information from the authentication ser-
     vice to the application or user. It is the responsibility of
     the PAM service modules to localize the messages. The memory
     used by pammessage has to be allocated  and  freed  by  the
     PAM  modules.   The  pammessage structure has the following
     entries:

       struct pammessage{
           int     msgstyle;
           char    *msg;
       };



     The message style, msgstyle, can be set to one of the  fol-
     lowing values:

     PAMPROMPTECHOF    Prompt  user,  disabling  echoing  of
                            response.


     PAMPROMPTECHON     Prompt  user,  enabling  echoing   of
                            response.


     PAMERORMSG          Print error message.


     PAMTEXTINFO          Print general text information.



     The maximum size of the message and the response  string  is
     PAMAXMSGSIZE as defined in .


     The structure pamresponse is  used  by  the  authentication
     service to get the user's response back from the application
     or user. The storage used by pamresponse has  to  be  allo-
     cated  by the application and freed by the  PAM modules. The
     pamresponse structure has the following entries:

       struct pamresponse{
           char *resp;
           int  respretcode;  /* currently not used, */
                               /* should be set to 0 */
        };







SunOS 5.11          Last change: 22 Feb 2005                    2






PAM Library Functions                             pamstart(3PAM)



     It is the responsibility of  the  conversation  function  to
     strip  off   NEWLINE  characters for PAMPROMPTECHOF and
     PAMPROMPTECHON message styles, and to add NEWLINE  char-
     acters  (if appropriate) for PAMERORMSG and PAMTEXTINFO
     message styles.


     The appdataptr argument  is  an  application  data  pointer
     which  is  passed  by  the  application  to the  PAM service
     modules. Since the  PAM modules pass  it  back  through  the
     conversation function, the applications can use this pointer
     to point to any application-specific data.


     The pamend() function is called to terminate the  authenti-
     cation  transaction  identified  by   pamh  and  to free any
     storage area allocated by  the  authentication  module.  The
     argument,  status,  is  passed  to  the  cleanup() function
     stored within the  pam handle, and is used to determine what
     module-specific state must be purged.  A cleanup function is
     attached to the handle by the underlying PAM modules through
     a call to pamsetdata(3PAM) to free module-specific data.


     Refer to Solaris Security for Developers Guide for  informa-
     tion  about  providing  authentication,  account management,
     session management,  and  password  management  through  PAM
     modules.

RETURN VALUES
     Refer to the RETURN VALUES section on pam(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
     libpam(3LIB),        pam(3PAM),         pamacctmgmt(3PAM),
     pamauthenticate(3PAM),                 pamchauthtok(3PAM),
     pamopensession(3PAM),                   pamsetcred(3PAM),
     pamsetdata(3PAM), pamstrerror(3PAM), attributes(5)



SunOS 5.11          Last change: 22 Feb 2005                    3






PAM Library Functions                             pamstart(3PAM)



     Solaris Security for Developers Guide

NOTES
     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: 22 Feb 2005                    4