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