pam_start(3)                                                   pam_start(3)




 NAME    [Toc]    [Back]
      pam_start, pam_end - authentication transaction routines for PAM

 SYNOPSIS    [Toc]    [Back]
      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    [Toc]    [Back]
      pam_start() is called to initiate an authentication 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 structure, pam_conv, and the address of a variable
      to be assigned the authentication handle, pamh.

      Upon successful completion, pamh will refer to a PAM handle for use
      with subsequent calls to the authentication library.

      The pam_conv structure, pam_conv, contains the address of the
      conversation function provided by the application.  The underlying PAM
      service module invokes this function to output information 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 */
           };

      where conv is:

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

      The function conv() 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 parameter num_msg 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 structure pam_message is used to pass prompt, error message, or
      any text information from the authentication service to the



 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 pam_start(3)                                                   pam_start(3)




      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 entries:

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

      The message style, msg_style, can be set to one of the following
      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.

      The maximum size of the message and the response string is
      PAM_MAX_MSG_SIZE 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 allocated 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 characters (if appropriate) for
      PAM_ERROR_MSG and PAM_TEXT_INFO message styles.

      appdata_ptr 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.

      pam_end() is called to terminate the authentication 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



 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 pam_start(3)                                                   pam_start(3)




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

 APPLICATION USAGE    [Toc]    [Back]
      Refer to pam(3) for information on thread-safety of PAM interfaces.

 RETURN VALUES    [Toc]    [Back]
      Refer to pam(3) for information on error related return values.

 SEE ALSO    [Toc]    [Back]
      pam_authenticate(3), pam_set_item(3), pam_acct_mgmt(3),
      pam_open_session(3), pam_setcred(3), pam_chauthtok(3),
      pam_strerror(3), pam(3).


 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003