An application must provide a ``conversation function''. It is used
for direct communication between a loaded module and the application
and will typically provide a means for the module to prompt the user
for a password etc. . The structure, pam_conv
, is defined by
including <security/pam_appl.h>
; 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, the argument
*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. That is to say, num_msg
holds the length of the array of pointers, msg
. After a
successful return, the pointer *resp
points to an array of
pam_response
structures, holding the application supplied text.
Note, *resp
is an struct pam_response
array and not an
array of pointers.
The message (from the module to the application) passing structure is
defined by <security/pam_appl.h>
as:
struct pam_message {
int msg_style;
const char *msg;
};
Valid choices for msg_style
are:
PAM_PROMPT_ECHO_OFF
Obtain a string without echoing any text
PAM_PROMPT_ECHO_ON
Obtain a string whilst echoing text
PAM_ERROR_MSG
Display an error
PAM_TEXT_INFO
Display some text.
The point of having an array of messages is that it becomes possible to pass a number of things to the application in a single call from the module. It can also be convenient for the application that related things come at once: a windows based application can then present a single form with many messages/prompts on at once.
The response (from the application to the module) passing structure is
defined by including <security/pam_appl.h>
as:
struct pam_response {
char *resp;
int resp_retcode;
};
Currently, there are no definitions for resp_retcode
values; the
normal value is 0
. The length of the *resp
array is known in
advance by the module, since it is dependent on the number of prompts
sent in the msg
array. The memory for this array and its string
elements should be dynamically allocated with one of the
malloc()
library of functions. It will be free()
'd by
the module.
The maximum length of the pam_msg.msg
and pam_response.resp
character strings is PAM_MAX_MSG_SIZE
.
PAM_SUCCESS
is the expected return value of this
function. However, should an error occur the application should not
set *resp
but simply return PAM_CONV_ERR
.
Note, if an application wishes to use two conversation functions, it
should activate the second with a call to pam_set_item()
.