1.\" $NetBSD: pam_conv.3,v 1.10 2023/06/30 21:46:20 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.Dd June 27, 2023 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 179.Fx 180Project by ThinkSec AS and Network Associates Laboratories, 181the Security Research Division of Network Associates, Inc. under 182DARPA/SPAWAR contract N66001-01-C-8035 183.Pq Dq CBOSS , 184as part of the DARPA CHATS research program. 185.Pp 186The OpenPAM library is maintained by 187.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no . 188