pam_start(3)pam_start(3)NAMEpam_start(), pam_end() - authentication transaction routines for PAM
SYNOPSIS
Command: [flag]... file... [library]...
DESCRIPTION
is called to initiate an authentication transaction. takes as argu‐
ments 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 authentica‐
tion 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 conversa‐
tion 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 is:
int conv(int num_msg,
const struct pam_message **msg, struct pam_response **resp,
void *appdata_ptr);
The 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 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 val‐
ues:
Prompt user, disabling echoing of response.
Prompt user, enabling echoing of response.
Print error message.
Print general text information.
The maximum size of the message and the response string is 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 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 new‐
line characters for and message styles, and to add newline characters
(if appropriate) for and 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.
is called to terminate the authentication transaction identified by
pamh and to free any storage area allocated by the authentication mod‐
ule. The argument, status, is passed to the 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(3) to free module specific
data.
APPLICATION USAGE
Refer to pam(3) for information on thread-safety of PAM interfaces.
RETURN VALUE
Refer to pam(3) for information on error related return values.
SEE ALSOpam_acct_mgmt(3), pam_authenticate(3), pam_chauthtok(3), pam_open_ses‐
sion(3), pam_set_item(3), pam_setcred(3), pam_strerror(3), pam(3).
pam_start(3)
