contrib/openpam/doc/man/pam_conv.3

   1 .\"-
   2 .\" Copyright (c) 2002-2003 Networks Associates Technology, Inc.
   3 .\" Copyright (c) 2004-2011 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 437 2011-09-13 12:00:13Z 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
  48 struct pam_message {
  49         int      msg_style;
  50         char    *msg;
  51 };
  52
  53 struct pam_response {
  54         char    *resp;
  55         int      resp_retcode;
  56 };
  57
  58 struct 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
  65 The PAM library uses an application-defined callback to communicate
  66 with the user.
  67 This callback is specified by the
  68 .Vt struct pam_conv
  69 passed to
  70 .Fn pam_start
  71 at the start of the transaction.
  72 It is also possible to set or change the conversation function at any
  73 point during a PAM transaction by changing the value of the
  74 .Dv PAM_CONV
  75 item.
  76 .Pp
  77 The conversation function's first argument specifies the number of
  78 messages (up to
  79 .Dv PAM_NUM_MSG )
  80 to process.
  81 The second argument is a pointer to an array of pointers to
  82 .Vt pam_message
  83 structures containing the actual messages.
  84 .Pp
  85 Each message can have one of four types, specified by the
  86 .Va msg_style
  87 member of
  88 .Vt struct pam_message :
  89 .Bl -tag -width 18n
  90 .It Dv PAM_PROMPT_ECHO_OFF
  91 Display a prompt and accept the user's response without echoing it to
  92 the terminal.
  93 This is commonly used for passwords.
  94 .It Dv PAM_PROMPT_ECHO_ON
  95 Display a prompt and accept the user's response, echoing it to the
  96 terminal.
  97 This is commonly used for login names and one-time passphrases.
  98 .It Dv PAM_ERROR_MSG
  99 Display an error message.
 100 .It Dv PAM_TEXT_INFO
 101 Display an informational message.
 102 .El
 103 .Pp
 104 In each case, the prompt or message to display is pointed to by the
 105 .Va msg
 106 member of
 107 .Vt struct pam_message .
 108 It can be up to
 109 .Dv PAM_MAX_MSG_SIZE
 110 characters long, including the terminating NUL.
 111 .Pp
 112 On success, the conversation function should allocate and fill a
 113 contiguous array of
 114 .Vt struct pam_response ,
 115 one for each message that was passed in.
 116 A pointer to the user's response to each message (or
 117 .Dv NULL
 118 in the case of informational or error messages) should be stored in
 119 the
 120 .Va resp
 121 member of the corresponding
 122 .Vt struct pam_response .
 123 Each response can be up to
 124 .Dv PAM_MAX_RESP_SIZE
 125 characters long, including the terminating NUL.
 126 .Pp
 127 The
 128 .Va resp_retcode
 129 member of
 130 .Vt struct pam_response
 131 is unused and should be set to zero.
 132 .Pp
 133 The conversation function should store a pointer to this array in the
 134 location pointed to by its third argument.
 135 It is the caller's responsibility to release both this array and the
 136 responses themselves, using
 137 .Xr free 3 .
 138 It is the conversation function's responsibility to ensure that it is
 139 legal to do so.
 140 .Pp
 141 The
 142 .Va appdata_ptr
 143 member of
 144 .Vt struct pam_conv
 145 is passed unmodified to the conversation function as its fourth and
 146 final argument.
 147 .Pp
 148 On failure, the conversation function should release any resources it
 149 has allocated, and return one of the predefined PAM error codes.
 150 .Sh RETURN VALUES
 151 The conversation function should return one of the following values:
 152 .Bl -tag -width 18n
 153 .It Bq Er PAM_BUF_ERR
 154 Memory buffer error.
 155 .It Bq Er PAM_CONV_ERR
 156 Conversation failure.
 157 .It Bq Er PAM_SUCCESS
 158 Success.
 159 .It Bq Er PAM_SYSTEM_ERR
 160 System 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
 178 The OpenPAM library and this manual page were developed for the
 179 FreeBSD Project by ThinkSec AS and Network Associates Laboratories,
 180 the Security Research Division of Network Associates, Inc.\& under
 181 DARPA/SPAWAR contract N66001-01-C-8035
 182 .Pq Dq CBOSS ,
 183 as part of the DARPA CHATS research program.