Current File : //usr/share/doc/pam-devel-1.1.8/html/adg-interface-of-app-expected.html
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>3.2. What is expected of an application</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="Linux-PAM_ADG.html" title="The Linux-PAM Application Developers' Guide"><link rel="up" href="adg-interface.html" title="Chapter 3. The public interface to Linux-PAM"><link rel="prev" href="adg-interface-by-app-expected.html" title="3.1. What can be expected by the application"><link rel="next" href="adg-interface-programming-notes.html" title="3.3. Programming notes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.2. What is expected of an application</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="adg-interface-by-app-expected.html">Prev</a> </td><th width="60%" align="center">Chapter 3.
The public interface to <span class="emphasis"><em>Linux-PAM</em></span>
</th><td width="20%" align="right"> <a accesskey="n" href="adg-interface-programming-notes.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="adg-interface-of-app-expected"></a>3.2. What is expected of an application</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="adg-pam_conv"></a>3.2.1. The conversation function</h3></div></div></div><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <security/pam_appl.h></pre></div><pre class="programlisting">
struct pam_message {
int msg_style;
const char *msg;
};
struct pam_response {
char *resp;
int resp_retcode;
};
struct pam_conv {
int (*conv)(int num_msg, const struct pam_message **msg,
struct pam_response **resp, void *appdata_ptr);
void *appdata_ptr;
};
</pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="adg-pam_conv-description"></a>3.2.1.1. DESCRIPTION</h4></div></div></div><p>
The PAM library uses an application-defined callback to allow
a direct communication between a loaded module and the application.
This callback is specified by the
<span class="emphasis"><em>struct pam_conv</em></span> passed to
<span class="citerefentry"><span class="refentrytitle">pam_start</span>(3)</span>
at the start of the transaction.
</p><p>
When a module calls the referenced conv() function, the argument
<span class="emphasis"><em>appdata_ptr</em></span> is set to the second element of
this structure.
</p><p>
The other arguments of a call to conv() concern the information
exchanged by module and application. That is to say,
<span class="emphasis"><em>num_msg</em></span> holds the length of the array of
pointers, <span class="emphasis"><em>msg</em></span>. After a successful return, the
pointer <span class="emphasis"><em>resp</em></span> points to an array of pam_response
structures, holding the application supplied text. The
<span class="emphasis"><em>resp_retcode</em></span> member of this struct is unused and
should be set to zero. It is the caller's responsibility to release
both, this array and the responses themselves, using
<span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>. Note, <span class="emphasis"><em>*resp</em></span> is a
<span class="emphasis"><em>struct pam_response</em></span> array and not an array of
pointers.
</p><p>
The number of responses is always equal to the
<span class="emphasis"><em>num_msg</em></span> conversation function argument.
This does require that the response array is
<span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>'d after
every call to the conversation function. The index of the
responses corresponds directly to the prompt index in the
pam_message array.
</p><p>
On failure, the conversation function should release any resources
it has allocated, and return one of the predefined PAM error codes.
</p><p>
Each message can have one of four types, specified by the
<span class="emphasis"><em>msg_style</em></span> member of
<span class="emphasis"><em>struct pam_message</em></span>:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">PAM_PROMPT_ECHO_OFF</span></dt><dd><p>
Obtain a string without echoing any text.
</p></dd><dt><span class="term">PAM_PROMPT_ECHO_ON</span></dt><dd><p>
Obtain a string whilst echoing text.
</p></dd><dt><span class="term">PAM_ERROR_MSG</span></dt><dd><p>
Display an error message.
</p></dd><dt><span class="term">PAM_TEXT_INFO</span></dt><dd><p>
Display some text.
</p></dd></dl></div><p>
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.
</p><p>
In passing, it is worth noting that there is a descrepency between
the way Linux-PAM handles the const struct pam_message **msg
conversation function argument from the way that Solaris' PAM
(and derivitives, known to include HP/UX, are there others?) does.
Linux-PAM interprets the msg argument as entirely equivalent to the
following prototype
const struct pam_message *msg[] (which, in spirit, is consistent with
the commonly used prototypes for argv argument to the familiar main()
function: char **argv; and char *argv[]). Said another way Linux-PAM
interprets the msg argument as a pointer to an array of num_msg read
only 'struct pam_message' pointers. Solaris' PAM implementation
interprets this argument as a pointer to a pointer to an array of
num_msg pam_message structures. Fortunately, perhaps, for most
module/application developers when num_msg has a value of one these
two definitions are entirely equivalent. Unfortunately, casually
raising this number to two has led to unanticipated compatibility
problems.
</p><p>
For what its worth the two known module writer work-arounds for trying
to maintain source level compatibility with both PAM implementations
are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
never call the conversation function with num_msg greater than one.
</p></li><li class="listitem"><p>
set up msg as doubly referenced so both types of conversation
function can find the messages. That is, make
</p><pre class="programlisting">
msg[n] = & (( *msg )[n])
</pre></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="adg-pam_conv-return_values"></a>3.2.1.2. RETURN VALUES</h4></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">PAM_BUF_ERR</span></dt><dd><p>
Memory buffer error.
</p></dd><dt><span class="term">PAM_CONV_ERR</span></dt><dd><p>
Conversation failure. The application should not set
<span class="emphasis"><em>*resp</em></span>.
</p></dd><dt><span class="term">PAM_SUCCESS</span></dt><dd><p>
Success.
</p></dd></dl></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="adg-interface-by-app-expected.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="adg-interface.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="adg-interface-programming-notes.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.1. What can be expected by the application </td><td width="20%" align="center"><a accesskey="h" href="Linux-PAM_ADG.html">Home</a></td><td width="40%" align="right" valign="top"> 3.3. Programming notes</td></tr></table></div></body></html>
Mini Shell