Manual Pages for UNIX Operating System command usage for man pam_start

PAM Library Functions                             pam_start(3PAM)



NAME
     pam_start, pam_end - PAM  authentication  transaction  func-
     tions

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

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



SunOS 5.11          Last change: 22 Feb 2005                    1






PAM Library Functions                             pam_start(3PAM)



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



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


     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 */
        };







SunOS 5.11          Last change: 22 Feb 2005                    2






PAM Library Functions                             pam_start(3PAM)



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


     Refer to Oracle Solaris Security for  Developers  Guide  for
     information  about providing authentication, account manage-
     ment, session management, and  password  management  through
     PAM modules.

RETURN VALUES
     Refer to the RETURN VALUES section on pam(3PAM).

ATTRIBUTES
     See attributes(5) for description of  the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | 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_data(3PAM), pam_strerror(3PAM), attributes(5)



SunOS 5.11          Last change: 22 Feb 2005                    3






PAM Library Functions                             pam_start(3PAM)



     Oracle 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