Edit File: 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>