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