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#4 $ 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_ttyconv 3 , 163.Xr openpam_nullconv 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. 183