Writing PAM Modules, Part Two
Pages: 1, 2, 3
The Conversation Function
An application may display a message in any number of formats. A GUI displays messages very differently from a command line interface, and both are different from a secure HTTP session or an FTP session.
PAM insulates the module developer from these issues, by requiring the application to provide a conversation function. This function takes messages from the module, presents them to the user, and provides the module with responses.
A call to pam_get_item(pamhandle, PAM_CONV, &item) produces a pointer to a conversation structure. The conversation structure contains the conversation function and a pointer that the application can use to transfer data.
struct pam_conv {
int (*conv)(int num_msg,
const struct pam_message **msg,
struct pam_response **resp,
void *appdata_ptr);
void *appdata_ptr;
};The module uses this function to pass messages to the user. The module may pass messages one at a time or as a cluster of several messages at once. The application will determine whether the messages are presented to the user as a group, or individually.
The module must create an array of pointers to pam_message structures to contain the message strings it needs the application to display. This array is the msg parameter, and each structure contains both the message and the message format. The num_msg parameter is the length of the message array.
struct pam_message {
int msg_style;
const char *msg;
};Available message formats are:
PAM_ERROR_MSG- Display an error message.
PAM_PROMPT_ECHO_OFF- Receive a string but do not echo input.
PAM_PROMPT_ECHO_ON- Receive a string and echo input.
PAM_TEXT_INFO- Display a message.
The application will provide an array of pam_response structures on return. The module must provide a pointer, which the application can fill with a pointer to the array. Yes, this is a complicated piece of indirection. The module provides its pointer as the resp parameter.
|
Related Reading Learning the Korn Shell |
The module should fill this pointer with a NULL or other testable value before calling the conversation function, so it can verify that the application has changed it.
struct pam_response {
char *resp;
int resp_retcode;
};
The resp_retcode in the response structure is currently meaningless, and is usually filled with a 0.
Note that the appdata_ptr is included as the last parameter of the function -- this is important. The application uses the appdata_ptr to transfer data it may need within the function, so be sure to send it that pointer.
Aside from PAM_SUCCESS, the conversation function might return PAM_CONV_ERR.
