PAM Library Functions                             pam_start(3PAM)

NAME
     pam_start, pam_end - authentication transaction routines for
     PAM

SYNOPSIS
     cc [ flag ... ] file ... -lpam [ library ... ]
     #include <security/pam_appl.h>

     int pam_start(const char *service, const char  *user,  const
     struct pam_conv *pam_conv, pam_handle_t **pamh);

     int pam_end(pam_handle_t *pamh, int status);

DESCRIPTION
     The pam_start() function is called to initiate an  authenti-
     cation  transaction. pam_start() takes as arguments the name
     of the current service, service, the name of the user to  be
     authenticated,  user, the address of the conversation struc-
     ture, pam_conv, 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  pam_conv 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 pam_conv
     structure has the following entries:

     struct pam_conv {
         int   (*conv)();     /* Conversation function */
         void  *appdata_ptr;  /* Application data */
     };

     int conv(int num_msg, const struct pam_message **msg,
              struct pam_response **resp, void *appdata_ptr);

     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 num_msg  parameter is the number of messages  associated
     with the call. The parameter msg is a pointer to an array of
     length num_msg of the pam_message structure.

     The pam_message 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 pam_message has to be allocated  and  freed  by  the
     PAM  modules.   The  pam_message structure has the following

SunOS 5.8           Last change: 22 Jul 1999                    1

PAM Library Functions                             pam_start(3PAM)

     entries:

     struct pam_message{
         int     msg_style;
         char    *msg;
     };

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

     PAM_PROMPT_ECHO_OFF
           Prompt user, disabling echoing of response.

     PAM_PROMPT_ECHO_ON
           Prompt user, enabling echoing of response.

     PAM_ERROR_MSG
           Print error message.

     PAM_TEXT_INFO
           Print general text information.

     PAM_MSG_NOCONF
           Print  general  text  information  without  user  ack-
           nowledgment.

     PAM_CONV_INTERRUPT
           Return from the conversation function.

     The maximum size of the message and the response  string  is
     PAM_MAX_MSG_SIZE as defined in <security/pam.appl.h>.

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

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

     It is the responsibility of  the  conversation  function  to
     strip  off   NEWLINE  characters for PAM_PROMPT_ECHO_OFF and
     PAM_PROMPT_ECHO_ON message styles, and to add NEWLINE  char-
     acters  (if appropriate) for PAM_ERROR_MSG and PAM_TEXT_INFO
     message styles.

     The appdata_ptr argument  is  an  application  data  pointer
     which  is  passed  by  the  application  to the  PAM service

SunOS 5.8           Last change: 22 Jul 1999                    2

PAM Library Functions                             pam_start(3PAM)

     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 pam_end() 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 pam_set_item(3PAM) to free module specific data.

RETURN VALUES
     Refer to pam(3PAM) for information on error  related  return
     values.

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
     libpam(3LIB),        pam(3PAM),         pam_acct_mgmt(3PAM),
     pam_authenticate(3PAM),                 pam_chauthtok(3PAM),
     pam_open_session(3PAM),                   pam_setcred(3PAM),
     pam_set_item(3PAM), pam_strerror(3PAM), attributes(5)

NOTES
     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: 22 Jul 1999                    3