2 .\" Copyright (c) 2002-2003 Networks Associates Technology, Inc.
3 .\" All rights reserved.
5 .\" This software was developed for the FreeBSD Project by ThinkSec AS and
6 .\" Network Associates Laboratories, the Security Research Division of
7 .\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
8 .\" ("CBOSS"), as part of the DARPA CHATS research program.
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
18 .\" 3. The name of the author may not be used to endorse or promote
19 .\" products derived from this software without specific prior written
22 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" $P4: //depot/projects/openpam/doc/man/pam_conv.3#4 $
41 .Nd PAM conversation system
45 .In security/pam_appl.h
58 int (*conv)(int, const struct pam_message **,
59 struct pam_response **, void *);
64 The PAM library uses an application-defined callback to communicate
66 This callback is specified by the
70 at the start of the transaction.
71 It is also possible to set or change the conversation function at any
72 point during a PAM transaction by changing the value of the
76 The conversation function's first argument specifies the number of
80 The second argument is a pointer to an array of pointers to
82 structures containing the actual messages.
84 Each message can have one of four types, specified by the
87 .Vt struct pam_message :
89 .It Dv PAM_PROMPT_ECHO_OFF
90 Display a prompt and accept the user's response without echoing it to
92 This is commonly used for passwords.
93 .It Dv PAM_PROMPT_ECHO_ON
94 Display a prompt and accept the user's response, echoing it to the
96 This is commonly used for login names and one-time passphrases.
98 Display an error message.
100 Display an informational message.
103 In each case, the prompt or message to display is pointed to by the
106 .Vt struct pam_message .
109 characters long, including the terminating NUL.
111 On success, the conversation function should allocate and fill a
113 .Vt struct pam_response ,
114 one for each message that was passed in.
115 A pointer to the user's response to each message (or
117 in the case of informational or error messages) should be stored in
120 member of the corresponding
121 .Vt struct pam_response .
122 Each response can be up to
123 .Dv PAM_MAX_RESP_SIZE
124 characters long, including the terminating NUL.
129 .Vt struct pam_response
130 is unused and should be set to zero.
132 The conversation function should store a pointer to this array in the
133 location pointed to by its third argument.
134 It is the caller's responsibility to release both this array and the
135 responses themselves, using
137 It is the conversation function's responsibility to ensure that it is
144 is passed unmodified to the conversation function as its fourth and
147 On failure, the conversation function should release any resources it
148 has allocated, and return one of the predefined PAM error codes.
150 The conversation function should return one of the following values:
152 .It Bq Er PAM_BUF_ERR
154 .It Bq Er PAM_CONV_ERR
155 Conversation failure.
156 .It Bq Er PAM_SUCCESS
158 .It Bq Er PAM_SYSTEM_ERR
162 .Xr openpam_nullconv 3 ,
163 .Xr openpam_ttyconv 3 ,
173 .%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
177 The OpenPAM library and this manual page were developed for the
178 FreeBSD Project by ThinkSec AS and Network Associates Laboratories,
179 the Security Research Division of Network Associates, Inc.\& under
180 DARPA/SPAWAR contract N66001-01-C-8035
182 as part of the DARPA CHATS research program.