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'>
6 <refentrytitle>pam_conv</refentrytitle>
7 <manvolnum>3</manvolnum>
8 <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
11 <refnamediv id="pam_conv-name">
12 <refname>pam_conv</refname>
13 <refpurpose>PAM conversation function</refpurpose>
16 <!-- body begins here -->
19 <funcsynopsis id="pam_conv-synopsis">
20 <funcsynopsisinfo>#include <security/pam_appl.h></funcsynopsisinfo>
34 int (*conv)(int num_msg, const struct pam_message **msg,
35 struct pam_response **resp, void *appdata_ptr);
41 <refsect1 id='pam_conv-description'>
42 <title>DESCRIPTION</title>
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
49 <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
51 at the start of the transaction.
54 When a module calls the referenced conv() function, the argument
55 <emphasis>appdata_ptr</emphasis> is set to the second element of
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
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
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
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
86 On failure, the conversation function should release any resources
87 it has allocated, and return one of the predefined PAM error codes.
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>:
96 <term>PAM_PROMPT_ECHO_OFF</term>
99 Obtain a string without echoing any text.
104 <term>PAM_PROMPT_ECHO_ON</term>
107 Obtain a string whilst echoing text.
112 <term>PAM_ERROR_MSG</term>
115 Display an error message.
120 <term>PAM_TEXT_INFO</term>
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.
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
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
155 For what its worth the two known module writer work-arounds for trying
156 to maintain source level compatibility with both PAM implementations
162 never call the conversation function with num_msg greater than one.
167 set up msg as doubly referenced so both types of conversation
168 function can find the messages. That is, make
171 msg[n] = & (( *msg )[n])
177 <refsect1 id="pam_conv-return_values">
178 <title>RETURN VALUES</title>
181 <term>PAM_BUF_ERR</term>
189 <term>PAM_CONV_ERR</term>
192 Conversation failure. The application should not set
193 <emphasis>*resp</emphasis>.
198 <term>PAM_SUCCESS</term>
208 <refsect1 id='pam_conv-see_also'>
209 <title>SEE ALSO</title>
212 <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
215 <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
218 <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
221 <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
224 <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>