pam_start

Name

pam_start -- initialize the PAM library

Synopsis

#include <security/pam_appl.h>

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

Description

pam_start() is used to initialize the PAM library. It must be called prior to any other usage of the PAM library. On success, *pamh becomes a handle that provides continuity for successive calls to the PAM library. pam_start() expects arguments as follows: the service_name of the program, the username of the individual to be authenticated, a pointer to an application-supplied pam_conv structure, and a pointer to a pam_handle_t pointer.

An application must provide the conversation function used for direct communication between a loaded module and the application. The application also typically provides a means for the module to prompt the user for a password, etc.

The structure, pam_conv, is defined to be,

  struct pam_conv {
               int (*conv) (int num_msg,
                            const struct pam_message * *msg,
                            struct pam_response * *resp,
                            void *appdata_ptr);
               void *appdata_ptr;
  };
It is initialized by the application before it is passed to the library. The contents of this structure are attached to the *pamh handle. The point of this argument is to provide a mechanism for any loaded module to interact directly with the application program; this is why it is called a conversation structure.

When a module calls the referenced conv() function, appdata_ptr is set to the second element of this structure.

The other arguments of a call to conv() concern the information exchanged by module and application. num_msg holds the length of the array of pointers passed via msg. On success, the pointer resp points to an array of num_msg pam_response structures, holding the application-supplied text. Note that resp is a struct pam_response array and not an array of pointers.

Return Value

PAM_SUCCESS 

Success.

PAM_BUF_ERR 

Memory allocation error.

PAM_ABORT 

Internal failure.

ERRORS

May be translated to text with pam_strerror().