granicus.if.org Git - linux-pam/blob - doc/man/pam_conv.3.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4 <refentry id='pam_conv'>
   5   <refmeta>
   6     <refentrytitle>pam_conv</refentrytitle>
   7     <manvolnum>3</manvolnum>
   8     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
   9   </refmeta>
  10
  11   <refnamediv id="pam_conv-name">
  12     <refname>pam_conv</refname>
  13     <refpurpose>PAM conversation function</refpurpose>
  14   </refnamediv>
  15
  16 <!-- body begins here -->
  17
  18   <refsynopsisdiv>
  19     <funcsynopsis id="pam_conv-synopsis">
  20       <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
  21     </funcsynopsis>
  22     <programlisting>
  23 struct pam_message {
  24     int msg_style;
  25     const char *msg;
  26 };
  27
  28 struct pam_response {
  29     char *resp;
  30     int resp_retcode;
  31 };
  32
  33 struct pam_conv {
  34     int (*conv)(int num_msg, const struct pam_message **msg,
  35                 struct pam_response **resp, void *appdata_ptr);
  36     void *appdata_ptr;
  37 };
  38     </programlisting>
  39   </refsynopsisdiv>
  40
  41   <refsect1 id='pam_conv-description'>
  42     <title>DESCRIPTION</title>
  43     <para>
  44       The PAM library uses an application-defined callback to allow
  45       a direct communication between a loaded module and the application.
  46       This callback is specified by the
  47       <emphasis>struct pam_conv</emphasis> passed to
  48       <citerefentry>
  49         <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
  50       </citerefentry>
  51       at the start of the transaction.
  52     </para>
  53     <para>
  54       When a module calls the referenced conv() function, the argument
  55       <emphasis>appdata_ptr</emphasis> is set to the second element of
  56       this structure.
  57     </para>
  58     <para>
  59       The other arguments of a call to conv() concern the information
  60       exchanged by module and application. That is to say,
  61       <emphasis>num_msg</emphasis> holds the length of the array of
  62       pointers, <emphasis>msg</emphasis>. After a successful return, the
  63       pointer <emphasis>resp</emphasis> points to an array of pam_response
  64       structures, holding the application supplied text. The
  65       <emphasis>resp_retcode</emphasis> member of this struct is unused and
  66       should be set to zero. It is the caller's responsibility to release
  67       both, this array and the responses themselves, using
  68       <citerefentry>
  69         <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
  70       </citerefentry>. Note, <emphasis>*resp</emphasis> is a
  71       <emphasis>struct pam_response</emphasis> array and not an array of
  72       pointers.
  73     </para>
  74     <para>
  75       The number of responses is always equal to the
  76       <emphasis>num_msg</emphasis> conversation function argument.
  77       This does require that the response array is
  78       <citerefentry>
  79         <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
  80       </citerefentry>'d after
  81       every call to the conversation function.  The index of the
  82       responses corresponds directly to the prompt index in the
  83       pam_message array.
  84     </para>
  85     <para>
  86       On failure, the conversation function should release any resources
  87       it has allocated, and return one of the predefined PAM error codes.
  88     </para>
  89     <para>
  90       Each message can have one of four types, specified by the
  91       <emphasis>msg_style</emphasis> member of
  92       <emphasis>struct pam_message</emphasis>:
  93     </para>
  94     <variablelist>
  95       <varlistentry>
  96         <term>PAM_PROMPT_ECHO_OFF</term>
  97         <listitem>
  98            <para>
  99              Obtain a string without echoing any text.
 100           </para>
 101         </listitem>
 102       </varlistentry>
 103       <varlistentry>
 104         <term>PAM_PROMPT_ECHO_ON</term>
 105         <listitem>
 106           <para>
 107             Obtain a string whilst echoing text.
 108           </para>
 109         </listitem>
 110       </varlistentry>
 111       <varlistentry>
 112         <term>PAM_ERROR_MSG</term>
 113         <listitem>
 114           <para>
 115             Display an error message.
 116           </para>
 117         </listitem>
 118       </varlistentry>
 119       <varlistentry>
 120         <term>PAM_TEXT_INFO</term>
 121         <listitem>
 122           <para>
 123             Display some text.
 124           </para>
 125         </listitem>
 126       </varlistentry>
 127     </variablelist>
 128     <para>
 129       The point of having an array of messages is that it becomes possible
 130       to pass a number of things to the application in a single call from
 131       the module. It can also be convenient for the application that related
 132       things come at once: a windows based application can then present a
 133       single form with many messages/prompts on at once.
 134     </para>
 135     <para>
 136       In passing, it is worth noting that there is a descrepency between
 137       the way Linux-PAM handles the const struct pam_message **msg
 138       conversation function argument from the way that Solaris' PAM
 139       (and derivitives, known to include HP/UX, are there others?) does.
 140       Linux-PAM interprets the msg argument as entirely equivalent to the
 141       following prototype
 142   const struct pam_message *msg[] (which, in spirit, is consistent with
 143   the commonly used prototypes for argv argument to the familiar main()
 144   function: char **argv; and char *argv[]). Said another way Linux-PAM
 145   interprets the msg argument as a pointer to an array of num_msg read
 146   only 'struct pam_message' pointers.  Solaris' PAM implementation
 147   interprets this argument as a pointer to a pointer to an array of
 148   num_msg pam_message structures.  Fortunately, perhaps, for most
 149   module/application developers when num_msg has a value of one these
 150   two definitions are entirely equivalent. Unfortunately, casually
 151   raising this number to two has led to unanticipated compatibility
 152   problems.
 153     </para>
 154     <para>
 155   For what its worth the two known module writer work-arounds for trying
 156   to maintain source level compatibility with both PAM implementations
 157   are:
 158     </para>
 159    <itemizedlist>
 160       <listitem>
 161         <para>
 162           never call the conversation function with num_msg greater than one.
 163         </para>
 164       </listitem>
 165       <listitem>
 166         <para>
 167           set up msg as doubly referenced so both types of conversation
 168           function can find the messages. That is, make
 169         </para>
 170         <programlisting>
 171        msg[n] = &amp; (( *msg )[n])
 172        </programlisting>
 173       </listitem>
 174     </itemizedlist>
 175   </refsect1>
 176
 177   <refsect1 id="pam_conv-return_values">
 178     <title>RETURN VALUES</title>
 179     <variablelist>
 180       <varlistentry>
 181         <term>PAM_BUF_ERR</term>
 182         <listitem>
 183            <para>
 184              Memory buffer error.
 185           </para>
 186         </listitem>
 187       </varlistentry>
 188       <varlistentry>
 189         <term>PAM_CONV_ERR</term>
 190         <listitem>
 191            <para>
 192              Conversation failure. The application should not set
 193              <emphasis>*resp</emphasis>.
 194           </para>
 195         </listitem>
 196       </varlistentry>
 197       <varlistentry>
 198         <term>PAM_SUCCESS</term>
 199         <listitem>
 200            <para>
 201              Success.
 202           </para>
 203         </listitem>
 204       </varlistentry>
 205     </variablelist>
 206   </refsect1>
 207
 208   <refsect1 id='pam_conv-see_also'>
 209     <title>SEE ALSO</title>
 210     <para>
 211       <citerefentry>
 212         <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
 213       </citerefentry>,
 214       <citerefentry>
 215         <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
 216       </citerefentry>,
 217       <citerefentry>
 218         <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
 219       </citerefentry>,
 220       <citerefentry>
 221         <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 222       </citerefentry>,
 223       <citerefentry>
 224         <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
 225       </citerefentry>
 226     </para>
 227   </refsect1>
 228 </refentry>