pam_start.3 (2010 09)

p
pam_start(3) pam_start(3)
NAME
pam_start(), pam_end() - authentication transaction routines for PAM
SYNOPSIS
Command:
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
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 authen-
tication 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 interac-
tion.
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 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.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1