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

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

Correct markup for email addresses.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 5.7 KB
Line 
1.\"-
2.\" Copyright (c) 2002-2003 Networks Associates Technology, Inc.
3.\" Copyright (c) 2004-2014 Dag-Erling Smørgrav
4.\" All rights reserved.
5.\"
6.\" This software was developed for the FreeBSD Project by ThinkSec AS and
7.\" Network Associates Laboratories, the Security Research Division of
8.\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
9.\" ("CBOSS"), as part of the DARPA CHATS research program.
10.\"
11.\" Redistribution and use in source and binary forms, with or without
12.\" modification, are permitted provided that the following conditions
13.\" are met:
14.\" 1. Redistributions of source code must retain the above copyright
15.\"    notice, this list of conditions and the following disclaimer.
16.\" 2. Redistributions in binary form must reproduce the above copyright
17.\"    notice, this list of conditions and the following disclaimer in the
18.\"    documentation and/or other materials provided with the distribution.
19.\" 3. The name of the author may not be used to endorse or promote
20.\"    products derived from this software without specific prior written
21.\"    permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\" $Id: pam_conv.3 910 2017-01-21 12:22:08Z des $
36.\"
37.Dd June 16, 2005
38.Dt PAM_CONV 3
39.Os
40.Sh NAME
41.Nm pam_conv
42.Nd PAM conversation system
43.Sh LIBRARY
44.Lb libpam
45.Sh SYNOPSIS
46.In security/pam_appl.h
47.Bd -literal
48struct pam_message {
49        int      msg_style;
50        char    *msg;
51};
52
53struct pam_response {
54        char    *resp;
55        int      resp_retcode;
56};
57
58struct pam_conv {
59        int     (*conv)(int, const struct pam_message **,
60            struct pam_response **, void *);
61        void    *appdata_ptr;
62};
63.Ed
64.Sh DESCRIPTION
65The PAM library uses an application-defined callback to communicate
66with the user.
67This callback is specified by the
68.Vt struct pam_conv
69passed to
70.Fn pam_start
71at the start of the transaction.
72It is also possible to set or change the conversation function at any
73point during a PAM transaction by changing the value of the
74.Dv PAM_CONV
75item.
76.Pp
77The conversation function's first argument specifies the number of
78messages (up to
79.Dv PAM_MAX_NUM_MSG )
80to process.
81The second argument is a pointer to an array of pointers to
82.Vt pam_message
83structures containing the actual messages.
84.Pp
85Each message can have one of four types, specified by the
86.Va msg_style
87member of
88.Vt struct pam_message :
89.Bl -tag -width 18n
90.It Dv PAM_PROMPT_ECHO_OFF
91Display a prompt and accept the user's response without echoing it to
92the terminal.
93This is commonly used for passwords.
94.It Dv PAM_PROMPT_ECHO_ON
95Display a prompt and accept the user's response, echoing it to the
96terminal.
97This is commonly used for login names and one-time passphrases.
98.It Dv PAM_ERROR_MSG
99Display an error message.
100.It Dv PAM_TEXT_INFO
101Display an informational message.
102.El
103.Pp
104In each case, the prompt or message to display is pointed to by the
105.Va msg
106member of
107.Vt struct pam_message .
108It can be up to
109.Dv PAM_MAX_MSG_SIZE
110characters long, including the terminating NUL.
111.Pp
112On success, the conversation function should allocate and fill a
113contiguous array of
114.Vt struct pam_response ,
115one for each message that was passed in.
116A pointer to the user's response to each message (or
117.Dv NULL
118in the case of informational or error messages) should be stored in
119the
120.Va resp
121member of the corresponding
122.Vt struct pam_response .
123Each response can be up to
124.Dv PAM_MAX_RESP_SIZE
125characters long, including the terminating NUL.
126.Pp
127The
128.Va resp_retcode
129member of
130.Vt struct pam_response
131is unused and should be set to zero.
132.Pp
133The conversation function should store a pointer to this array in the
134location pointed to by its third argument.
135It is the caller's responsibility to release both this array and the
136responses themselves, using
137.Xr free 3 .
138It is the conversation function's responsibility to ensure that it is
139legal to do so.
140.Pp
141The
142.Va appdata_ptr
143member of
144.Vt struct pam_conv
145is passed unmodified to the conversation function as its fourth and
146final argument.
147.Pp
148On failure, the conversation function should release any resources it
149has allocated, and return one of the predefined PAM error codes.
150.Sh RETURN VALUES
151The conversation function should return one of the following values:
152.Bl -tag -width 18n
153.It Bq Er PAM_BUF_ERR
154Memory buffer error.
155.It Bq Er PAM_CONV_ERR
156Conversation failure.
157.It Bq Er PAM_SUCCESS
158Success.
159.It Bq Er PAM_SYSTEM_ERR
160System error.
161.El
162.Sh SEE ALSO
163.Xr openpam_nullconv 3 ,
164.Xr openpam_ttyconv 3 ,
165.Xr pam 3 ,
166.Xr pam_error 3 ,
167.Xr pam_get_item 3 ,
168.Xr pam_info 3 ,
169.Xr pam_prompt 3 ,
170.Xr pam_set_item 3 ,
171.Xr pam_start 3
172.Sh STANDARDS
173.Rs
174.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
175.%D "June 1997"
176.Re
177.Sh AUTHORS
178The OpenPAM library and this manual page were developed for the
179FreeBSD Project by ThinkSec AS and Network Associates Laboratories,
180the Security Research Division of Network Associates, Inc.\& under
181DARPA/SPAWAR contract N66001-01-C-8035
182.Pq Dq CBOSS ,
183as part of the DARPA CHATS research program.
184.Pp
185The OpenPAM library is maintained by
186.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .
Note: See TracBrowser for help on using the repository browser.