libpam-doc 1.1.3-7ubuntu2 / usr / share / doc / libpam-doc / html / adg-interface-of-app-expected.html

This file is indexed.

/usr/share/doc/libpam-doc/html/adg-interface-of-app-expected.html is in libpam-doc 1.1.3-7ubuntu2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
<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.76.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" title="3.2. What is expected of an application"><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" title="3.2.1. The conversation function"><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 &lt;security/pam_appl.h&gt;</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" title="3.2.1.1. DESCRIPTION"><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><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" 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] = &amp; (( *msg )[n])
       </pre></li></ul></div></div><div class="section" title="3.2.1.2. RETURN VALUES"><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><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>

APT Browse - Built by Thomas Orozco.