source: openpam/trunk/doc/man/pam_conv.3 @ 314

Last change on this file since 314 was 314, checked in by Dag-Erling Smørgrav, 14 years ago

Fix xref ordering and single space after Inc.

Submitted by: ru

File size: 5.6 KB
Line 
1.\"-
2.\" Copyright (c) 2002-2003 Networks Associates Technology, Inc.
3.\" All rights reserved.
4.\"
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.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
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
20.\"    permission.
21.\"
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
32.\" SUCH DAMAGE.
33.\"
34.\" $P4: //depot/projects/openpam/doc/man/pam_conv.3#5 $
35.\"
36.Dd May 27, 2002
37.Dt PAM_CONV 3
38.Os
39.Sh NAME
40.Nm pam_conv
41.Nd PAM conversation system
42.Sh LIBRARY
43.Lb libpam
44.Sh SYNOPSIS
45.In security/pam_appl.h
46.Bd -literal
47struct pam_message {
48        int      msg_style;
49        char    *msg;
50};
51
52struct pam_response {
53        char    *resp;
54        int      resp_retcode;
55};
56
57struct pam_conv {
58        int     (*conv)(int, const struct pam_message **,
59            struct pam_response **, void *);
60        void    *appdata_ptr;
61};
62.Ed
63.Sh DESCRIPTION
64The PAM library uses an application-defined callback to communicate
65with the user.
66This callback is specified by the
67.Vt struct pam_conv
68passed to
69.Fn pam_start
70at the start of the transaction.
71It is also possible to set or change the conversation function at any
72point during a PAM transaction by changing the value of the
73.Dv PAM_CONV
74item.
75.Pp
76The conversation function's first argument specifies the number of
77messages (up to
78.Dv PAM_NUM_MSG )
79to process.
80The second argument is a pointer to an array of pointers to
81.Vt pam_message
82structures containing the actual messages.
83.Pp
84Each message can have one of four types, specified by the
85.Va msg_style
86member of
87.Vt struct pam_message :
88.Bl -tag -width 18n
89.It Dv PAM_PROMPT_ECHO_OFF
90Display a prompt and accept the user's response without echoing it to
91the terminal.
92This is commonly used for passwords.
93.It Dv PAM_PROMPT_ECHO_ON
94Display a prompt and accept the user's response, echoing it to the
95terminal.
96This is commonly used for login names and one-time passphrases.
97.It Dv PAM_ERROR_MSG
98Display an error message.
99.It Dv PAM_TEXT_INFO
100Display an informational message.
101.El
102.Pp
103In each case, the prompt or message to display is pointed to by the
104.Va msg
105member of
106.Vt struct pam_message .
107It can be up to
108.Dv PAM_MAX_MSG_SIZE
109characters long, including the terminating NUL.
110.Pp
111On success, the conversation function should allocate and fill a
112contiguous array of
113.Vt struct pam_response ,
114one for each message that was passed in.
115A pointer to the user's response to each message (or
116.Dv NULL
117in the case of informational or error messages) should be stored in
118the
119.Va resp
120member of the corresponding
121.Vt struct pam_response .
122Each response can be up to
123.Dv PAM_MAX_RESP_SIZE
124characters long, including the terminating NUL.
125.Pp
126The
127.Va resp_retcode
128member of
129.Vt struct pam_response
130is unused and should be set to zero.
131.Pp
132The conversation function should store a pointer to this array in the
133location pointed to by its third argument.
134It is the caller's responsibility to release both this array and the
135responses themselves, using
136.Xr free 3 .
137It is the conversation function's responsibility to ensure that it is
138legal to do so.
139.Pp
140The
141.Va appdata_ptr
142member of
143.Vt struct pam_conv
144is passed unmodified to the conversation function as its fourth and
145final argument.
146.Pp
147On failure, the conversation function should release any resources it
148has allocated, and return one of the predefined PAM error codes.
149.Sh RETURN VALUES
150The conversation function should return one of the following values:
151.Bl -tag -width 18n
152.It Bq Er PAM_BUF_ERR
153Memory buffer error.
154.It Bq Er PAM_CONV_ERR
155Conversation failure.
156.It Bq Er PAM_SUCCESS
157Success.
158.It Bq Er PAM_SYSTEM_ERR
159System error.
160.El
161.Sh SEE ALSO
162.Xr openpam_nullconv 3 ,
163.Xr openpam_ttyconv 3 ,
164.Xr pam 3 ,
165.Xr pam_error 3 ,
166.Xr pam_get_item 3 ,
167.Xr pam_info 3 ,
168.Xr pam_prompt 3 ,
169.Xr pam_set_item 3 ,
170.Xr pam_start 3
171.Sh STANDARDS
172.Rs
173.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
174.%D "June 1997"
175.Re
176.Sh AUTHORS
177The OpenPAM library and this manual page were developed for the
178FreeBSD Project by ThinkSec AS and Network Associates Laboratories,
179the Security Research Division of Network Associates, Inc.\& under
180DARPA/SPAWAR contract N66001-01-C-8035
181.Pq Dq CBOSS ,
182as part of the DARPA CHATS research program.
Note: See TracBrowser for help on using the repository browser.